tree_haver 1.0.0

data/README.md

@@ -0,0 +1,1260 @@
+| 📍 NOTE                                                                                                                                                                                                       |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| RubyGems (the [GitHub org][rubygems-org], not the website) [suffered][draper-security] a [hostile takeover][ellen-takeover] in September 2025.                                                                |
+| Ultimately [4 maintainers][simi-removed] were [hard removed][martin-removed] and a reason has been given for only 1 of those, while 2 others resigned in protest.                                             |
+| It is a [complicated story][draper-takeover] which is difficult to [parse quickly][draper-lies].                                                                                                              |
+| Simply put - there was active policy for adding or removing maintainers/owners of [rubygems][rubygems-maint-policy] and [bundler][bundler-maint-policy], and those [policies were not followed][policy-fail]. |
+| I'm adding notes like this to gems because I [don't condone theft][draper-theft] of repositories or gems from their rightful owners.                                                                          |
+| If a similar theft happened with my repos/gems, I'd hope some would stand up for me.                                                                                                                          |
+| Disenfranchised former-maintainers have started [gem.coop][gem-coop].                                                                                                                                         |
+| Once available I will publish there exclusively; unless RubyCentral makes amends with the community.                                                                                                          |
+| The ["Technology for Humans: Joel Draper"][reinteractive-podcast] podcast episode by [reinteractive][reinteractive] is the most cogent summary I'm aware of.                                                  |
+| See [here][gem-naming], [here][gem-coop] and [here][martin-ann] for more info on what comes next.                                                                                                             |
+| What I'm doing: A (WIP) proposal for [bundler/gem scopes][gem-scopes], and a (WIP) proposal for a federated [gem server][gem-server].                                                                         |
+
+[rubygems-org]: https://github.com/rubygems/
+[draper-security]: https://joel.drapper.me/p/ruby-central-security-measures/
+[draper-takeover]: https://joel.drapper.me/p/ruby-central-takeover/
+[ellen-takeover]: https://pup-e.com/blog/goodbye-rubygems/
+[simi-removed]: https://www.reddit.com/r/ruby/s/gOk42POCaV
+[martin-removed]: https://bsky.app/profile/martinemde.com/post/3m3occezxxs2q
+[draper-lies]: https://joel.drapper.me/p/ruby-central-fact-check/
+[draper-theft]: https://joel.drapper.me/p/ruby-central/
+[reinteractive]: https://reinteractive.com/ruby-on-rails
+[gem-coop]: https://gem.coop
+[gem-naming]: https://github.com/gem-coop/gem.coop/issues/12
+[martin-ann]: https://martinemde.com/2025/10/05/announcing-gem-coop.html
+[gem-scopes]: https://github.com/galtzo-floss/bundle-namespace
+[gem-server]: https://github.com/galtzo-floss/gem-server
+[reinteractive-podcast]: https://youtu.be/_H4qbtC5qzU?si=BvuBU90R2wAqD2E6
+[bundler-maint-policy]: https://github.com/ruby/rubygems/blob/b1ab33a3d52310a84d16b193991af07f5a6a07c0/doc/bundler/playbooks/TEAM_CHANGES.md
+[rubygems-maint-policy]: https://github.com/ruby/rubygems/blob/b1ab33a3d52310a84d16b193991af07f5a6a07c0/doc/rubygems/POLICIES.md?plain=1#L187-L196
+[policy-fail]: https://www.reddit.com/r/ruby/comments/1ove9vp/rubycentral_hates_this_one_fact/
+
+[![Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0][🖼️galtzo-i]][🖼️galtzo-discord] [![ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5][🖼️ruby-lang-i]][🖼️ruby-lang] [![kettle-rb Logo by Aboling0, CC BY-SA 4.0][🖼️kettle-rb-i]][🖼️kettle-rb]
+
+[🖼️galtzo-i]: https://logos.galtzo.com/assets/images/galtzo-floss/avatar-192px.svg
+[🖼️galtzo-discord]: https://discord.gg/3qme4XHNKN
+[🖼️ruby-lang-i]: https://logos.galtzo.com/assets/images/ruby-lang/avatar-192px.svg
+[🖼️ruby-lang]: https://www.ruby-lang.org/
+[🖼️kettle-rb-i]: https://logos.galtzo.com/assets/images/kettle-rb/avatar-192px.svg
+[🖼️kettle-rb]: https://github.com/kettle-rb
+
+# 🌴 TreeHaver
+
+[![Version][👽versioni]][👽version] [![GitHub tag (latest SemVer)][⛳️tag-img]][⛳️tag] [![License: MIT][📄license-img]][📄license-ref] [![Downloads Rank][👽dl-ranki]][👽dl-rank] [![Open Source Helpers][👽oss-helpi]][👽oss-help] [![CodeCov Test Coverage][🏀codecovi]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] [![QLTY Maintainability][🏀qlty-mnti]][🏀qlty-mnt] [![CI Heads][🚎3-hd-wfi]][🚎3-hd-wf] [![CI Runtime Dependencies @ HEAD][🚎12-crh-wfi]][🚎12-crh-wf] [![CI Current][🚎11-c-wfi]][🚎11-c-wf] [![CI Truffle Ruby][🚎9-t-wfi]][🚎9-t-wf] [![Deps Locked][🚎13-🔒️-wfi]][🚎13-🔒️-wf] [![Deps Unlocked][🚎14-🔓️-wfi]][🚎14-🔓️-wf] [![CI Supported][🚎6-s-wfi]][🚎6-s-wf] [![CI Test Coverage][🚎2-cov-wfi]][🚎2-cov-wf] [![CI Style][🚎5-st-wfi]][🚎5-st-wf] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Apache SkyWalking Eyes License Compatibility Check][🚎15-🪪-wfi]][🚎15-🪪-wf]
+
+`if ci_badges.map(&:color).detect { it != "green"}` ☝️ [let me know][🖼️galtzo-discord], as I may have missed the [discord notification][🖼️galtzo-discord].
+
+---
+
+`if ci_badges.map(&:color).all? { it == "green"}` 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
+
+[![OpenCollective Backers][🖇osc-backers-i]][🖇osc-backers] [![OpenCollective Sponsors][🖇osc-sponsors-i]][🖇osc-sponsors] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate at ko-fi.com][🖇kofi-img]][🖇kofi]
+
+## 🌻 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.
+
+### 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 |
+
+**Write once, run anywhere.** Just as Faraday lets you swap HTTP adapters without changing your code, TreeHaver lets you swap Tree-sitter backends. Your parsing code remains the same whether you're running on MRI with native C extensions, JRuby with FFI, or TruffleRuby.
+
+```ruby
+# Your code stays the same regardless of backend
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Language.from_library("/path/to/grammar.so")
+tree = parser.parse(source_code)
+
+# TreeHaver automatically picks the best backend:
+# - MRI → ruby_tree_sitter (C extension)
+# - JRuby → FFI (system's libtree-sitter)
+# - TruffleRuby → FFI or MRI backend
+```
+
+### 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
+- **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.)
+- **Grammar Discovery**: Built-in `GrammarFinder` utility for platform-aware grammar library discovery
+- **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
+
+### Why TreeHaver?
+
+Tree-sitter is a powerful parser generator that creates incremental parsers for many programming languages. However, integrating it into Ruby applications can be challenging:
+
+- MRI-based C extensions don't work on JRuby
+- FFI-based solutions may not be optimal for MRI
+- Managing different backends for different Ruby implementations is cumbersome
+
+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.
+
+### Comparison with Other Ruby Tree-sitter Bindings
+
+| Feature                   | TreeHaver                      | [ruby_tree_sitter] | [tree_stump]   |
+|---------------------------|--------------------------------|--------------------|----------------|
+| **MRI Ruby**              | ✅ Yes                          | ✅ Yes              | ✅ Yes          |
+| **JRuby**                 | ✅ Yes (FFI or Java\* backend)  | ❌ No               | ❌ No           |
+| **TruffleRuby**           | ✅ Yes (FFI)                    | ❌ No               | ❓ Unknown      |
+| **Backend**               | Multi (MRI C, Rust, FFI, Java) | C extension only   | Rust extension |
+| **Incremental Parsing**   | ✅ Via MRI C/Rust backend       | ✅ Yes              | ✅ Yes          |
+| **Query API**             | ⚡ Via MRI/Rust backend         | ✅ Yes              | ✅ Yes          |
+| **Grammar Discovery**     | ✅ Built-in `GrammarFinder`     | ❌ Manual           | ❌ Manual       |
+| **Security Validations**  | ✅ `PathValidator`              | ❌ No               | ❌ No           |
+| **Language Registration** | ✅ Thread-safe registry         | ❌ No               | ❌ No           |
+| **Native Performance**    | ⚡ Backend-dependent            | ✅ Native C         | ✅ Native Rust  |
+| **Precompiled Binaries**  | ⚡ Via Rust backend             | ✅ Yes              | ✅ Yes          |
+| **Minimum Ruby**          | 3.2+                           | 3.0+               | 3.1+           |
+
+[ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
+[tree_stump]: https://github.com/anthropics/tree_stump
+
+**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:** 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:** `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.
+
+#### When to Use Each
+
+**Choose TreeHaver when:**
+- You need JRuby or TruffleRuby support
+- You're building a library that should work across Ruby implementations
+- You want automatic grammar discovery and security validations
+- You want flexibility to switch backends without code changes
+- You need incremental parsing with a unified API
+
+**Choose ruby_tree_sitter directly when:**
+- You only target MRI Ruby
+- You need the full Query API without abstraction
+- You want the most battle-tested C bindings
+- You don't need TreeHaver's grammar discovery
+
+**Choose tree_stump directly when:**
+- You only target MRI Ruby
+- 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
+
+## 💡 Info you can shake a stick at
+
+| Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                                                          |
+|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Works with JRuby        | [![JRuby 10.0 Compat][💎jruby-c-i]][🚎11-c-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf]                                                                                                          |
+| Works with Truffle Ruby | [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎9-t-wf] [![Truffle Ruby 24.1 Compat][💎truby-c-i]][🚎11-c-wf]                                                                                                                                                            |
+| Works with MRI Ruby 3   | [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎6-s-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎6-s-wf] [![Ruby 3.4 Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]                                                                                         |
+| Support & Community     | [![Join Me on Daily.dev's RubyFriends][✉️ruby-friends-img]][✉️ruby-friends] [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]                                       |
+| Source                  | [![Source on GitLab.com][📜src-gl-img]][📜src-gl] [![Source on CodeBerg.org][📜src-cb-img]][📜src-cb] [![Source on Github.com][📜src-gh-img]][📜src-gh] [![The best SHA: dQw4w9WgXcQ!][🧮kloc-img]][🧮kloc]                                                                                                                                                         |
+| Documentation           | [![Current release on RubyDoc.info][📜docs-cr-rd-img]][🚎yard-current] [![YARD on Galtzo.com][📜docs-head-rd-img]][🚎yard-head] [![Maintainer Blog][🚂maint-blog-img]][🚂maint-blog] [![GitLab Wiki][📜gl-wiki-img]][📜gl-wiki] [![GitHub Wiki][📜gh-wiki-img]][📜gh-wiki]                                                                                          |
+| Compliance              | [![License: MIT][📄license-img]][📄license-ref] [![Compatible with Apache Software Projects: Verified by SkyWalking Eyes][📄license-compat-img]][📄license-compat] [![📄ilo-declaration-img]][📄ilo-declaration] [![Security Policy][🔐security-img]][🔐security] [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct] [![SemVer 2.0.0][📌semver-img]][📌semver] |
+| Style                   | [![Enforced Code Style Linter][💎rlts-img]][💎rlts] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] [![Gitmoji Commits][📌gitmoji-img]][📌gitmoji] [![Compatibility appraised by: appraisal2][💎appraisal2-img]][💎appraisal2]                                                                                                                  |
+| Maintainer 🎖️          | [![Follow Me on LinkedIn][💖🖇linkedin-img]][💖🖇linkedin] [![Follow Me on Ruby.Social][💖🐘ruby-mast-img]][💖🐘ruby-mast] [![Follow Me on Bluesky][💖🦋bluesky-img]][💖🦋bluesky] [![Contact Maintainer][🚂maint-contact-img]][🚂maint-contact] [![My technical writing][💖💁🏼‍♂️devto-img]][💖💁🏼‍♂️devto]                                                      |
+| `...` 💖                | [![Find Me on WellFound:][💖✌️wellfound-img]][💖✌️wellfound] [![Find Me on CrunchBase][💖💲crunchbase-img]][💖💲crunchbase] [![My LinkTree][💖🌳linktree-img]][💖🌳linktree] [![More About Me][💖💁🏼‍♂️aboutme-img]][💖💁🏼‍♂️aboutme] [🧊][💖🧊berg] [🐙][💖🐙hub]  [🛖][💖🛖hut] [🧪][💖🧪lab]                                                                   |
+
+### Compatibility
+
+Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRuby.
+
+| 🚚 _Amazing_ test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚             |
+|------------------------------------------------|--------------------------------------------------------|
+| 👟 Check it out!                               | ✨ [github.com/appraisal-rb/appraisal2][💎appraisal2] ✨ |
+
+### Federated DVCS
+
+<details markdown="1">
+  <summary>Find this repo on federated forges (Coming soon!)</summary>
+
+| Federated [DVCS][💎d-in-dvcs] Repository        | Status                                                                | Issues                    | PRs                      | Wiki                      | CI                       | Discussions                  |
+|-------------------------------------------------|-----------------------------------------------------------------------|---------------------------|--------------------------|---------------------------|--------------------------|------------------------------|
+| 🧪 [kettle-rb/tree_haver on GitLab][📜src-gl]   | The Truth                                                             | [💚][🤝gl-issues]         | [💚][🤝gl-pulls]         | [💚][📜gl-wiki]           | 🐭 Tiny Matrix           | ➖                            |
+| 🧊 [kettle-rb/tree_haver on CodeBerg][📜src-cb] | An Ethical Mirror ([Donate][🤝cb-donate])                             | [💚][🤝cb-issues]         | [💚][🤝cb-pulls]         | ➖                         | ⭕️ No Matrix             | ➖                            |
+| 🐙 [kettle-rb/tree_haver on GitHub][📜src-gh]   | Another Mirror                                                        | [💚][🤝gh-issues]         | [💚][🤝gh-pulls]         | [💚][📜gh-wiki]           | 💯 Full Matrix           | [💚][gh-discussions]         |
+| 🎮️ [Discord Server][✉️discord-invite]          | [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] | [Let's][✉️discord-invite] | [talk][✉️discord-invite] | [about][✉️discord-invite] | [this][✉️discord-invite] | [library!][✉️discord-invite] |
+
+</details>
+
+[gh-discussions]: https://github.com/kettle-rb/tree_haver/discussions
+
+### Enterprise Support [![Tidelift](https://tidelift.com/badges/package/rubygems/tree_haver)](https://tidelift.com/subscription/pkg/rubygems-tree_haver?utm_source=rubygems-tree_haver&utm_medium=referral&utm_campaign=readme)
+
+Available as part of the Tidelift Subscription.
+
+<details markdown="1">
+  <summary>Need enterprise-level guarantees?</summary>
+
+The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
+
+[![Get help from me on Tidelift][🏙️entsup-tidelift-img]][🏙️entsup-tidelift]
+
+- 💡Subscribe for support guarantees covering _all_ your FLOSS dependencies
+- 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar]
+- 💡Tidelift pays maintainers to maintain the software you depend on!<br/>📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers
+
+Alternatively:
+
+- [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite]
+- [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork]
+- [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]
+
+</details>
+
+## ✨ Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```console
+bundle add tree_haver
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```console
+gem install tree_haver
+```
+
+### 🔒 Secure Installation
+
+<details markdown="1">
+  <summary>For Medium or High Security Installations</summary>
+
+This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by
+[stone_checksums][💎stone_checksums]. Be sure the gem you install hasn’t been tampered with
+by following the instructions below.
+
+Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:
+
+```console
+gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem)
+```
+
+You only need to do that once.  Then proceed to install with:
+
+```console
+gem install tree_haver -P HighSecurity
+```
+
+The `HighSecurity` trust profile will verify signed gems, and not allow the installation of unsigned dependencies.
+
+If you want to up your security game full-time:
+
+```console
+bundle config set --global trust-policy MediumSecurity
+```
+
+`MediumSecurity` instead of `HighSecurity` is necessary if not all the gems you use are signed.
+
+NOTE: Be prepared to track down certs for signed gems and add them the same way you added mine.
+
+</details>
+
+## ⚙️ Configuration
+
+### Security Considerations
+
+**⚠️ Loading shared libraries (.so/.dylib/.dll) executes arbitrary native code.**
+
+TreeHaver provides defense-in-depth validations, but you should understand the risks:
+
+#### Attack Vectors Mitigated
+
+TreeHaver's `PathValidator` module protects against:
+
+- **Path traversal**: Paths containing `/../` or `/./` are rejected
+- **Null byte injection**: Paths containing null bytes are rejected
+- **Non-absolute paths**: Relative paths are rejected to prevent CWD-based attacks
+- **Invalid extensions**: Only `.so`, `.dylib`, and `.dll` files are accepted
+- **Malicious filenames**: Filenames must match a safe pattern (alphanumeric, hyphens, underscores)
+- **Invalid language names**: Language names must be lowercase alphanumeric with underscores
+- **Invalid symbol names**: Symbol names must be valid C identifiers
+
+#### Secure Usage
+
+```ruby
+# Standard usage - paths from ENV are validated
+finder = TreeHaver::GrammarFinder.new(:toml)
+path = finder.find_library_path  # Validates ENV path before returning
+
+# Maximum security - only trusted system directories
+path = finder.find_library_path_safe  # Ignores ENV, only /usr/lib etc.
+
+# Manual validation
+if TreeHaver::PathValidator.safe_library_path?(user_provided_path)
+  language = TreeHaver::Language.from_library(user_provided_path)
+end
+
+# Get validation errors for debugging
+errors = TreeHaver::PathValidator.validation_errors(path)
+# => ["Path is not absolute", "Path contains traversal sequence"]
+```
+
+#### Trusted Directories
+
+The `find_library_path_safe` method only returns paths in trusted directories.
+
+**Default trusted directories:**
+
+- `/usr/lib`, `/usr/lib64`
+- `/usr/lib/x86_64-linux-gnu`, `/usr/lib/aarch64-linux-gnu`
+- `/usr/local/lib`
+- `/opt/homebrew/lib`, `/opt/local/lib`
+
+**Adding custom trusted directories:**
+
+For non-standard installations (Homebrew on Linux, luarocks, mise, asdf, etc.), register additional trusted directories:
+
+```ruby
+# Programmatically at application startup
+TreeHaver::PathValidator.add_trusted_directory("/home/linuxbrew/.linuxbrew/Cellar")
+TreeHaver::PathValidator.add_trusted_directory("~/.local/share/mise/installs/lua")
+
+# Or via environment variable (comma-separated, in your shell profile)
+export TREE_HAVER_TRUSTED_DIRS = "/home/linuxbrew/.linuxbrew/Cellar,~/.local/share/mise/installs/lua"
+```
+
+**Example: Fedora Silverblue with Homebrew and luarocks**
+
+```bash
+# In ~/.bashrc or ~/.zshrc
+export TREE_HAVER_TRUSTED_DIRS="/home/linuxbrew/.linuxbrew/Cellar,~/.local/share/mise/installs/lua"
+
+# tree-sitter runtime library
+export TREE_SITTER_RUNTIME_LIB=/home/linuxbrew/.linuxbrew/Cellar/tree-sitter/0.26.3/lib/libtree-sitter.so
+
+# Language grammar (luarocks-installed)
+export TREE_SITTER_TOML_PATH=~/.local/share/mise/installs/lua/5.4.8/luarocks/lib/luarocks/rocks-5.4/tree-sitter-toml/0.0.31-1/parser/toml.so
+```
+
+#### Recommendations
+
+1. **Production**: Consider using `find_library_path_safe` to ignore ENV overrides
+2. **Development**: Standard `find_library_path` is convenient for testing
+3. **User Input**: Always validate paths before passing to `Language.from_library`
+4. **CI/CD**: Be cautious of ENV vars that could be set by untrusted sources
+5. **Custom installs**: Register trusted directories via `TREE_HAVER_TRUSTED_DIRS` or `add_trusted_directory`
+
+### Backend Selection
+
+TreeHaver automatically selects the best backend for your Ruby implementation, but you can override this behavior:
+
+```ruby
+# Automatic backend selection (default)
+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
+TreeHaver.backend = :ffi   # Use FFI bindings (works on MRI and JRuby)
+TreeHaver.backend = :java  # Use Java bindings (JRuby only, coming soon)
+```
+
+**Auto-selection priority on MRI:** MRI → Rust → FFI
+
+You can also set the backend via environment variable:
+
+```bash
+export TREE_HAVER_BACKEND=rust
+```
+
+### Environment Variables
+
+TreeHaver recognizes several environment variables for configuration:
+
+**Note**: All path-based environment variables are validated before use. Invalid paths are ignored.
+
+#### Security Configuration
+
+- **`TREE_HAVER_TRUSTED_DIRS`**: Comma-separated list of additional trusted directories for grammar libraries
+  ```bash
+  # For Homebrew on Linux and luarocks
+  export TREE_HAVER_TRUSTED_DIRS="/home/linuxbrew/.linuxbrew/Cellar,~/.local/share/mise/installs/lua"
+  ```
+
+  Tilde (`~`) is expanded to the user's home directory. Directories listed here are considered safe for `find_library_path_safe`.
+
+#### Core Runtime Library
+
+- **`TREE_SITTER_RUNTIME_LIB`**: Absolute path to the core `libtree-sitter` shared library
+  ```bash
+  export TREE_SITTER_RUNTIME_LIB=/usr/local/lib/libtree-sitter.so
+  ```
+
+If not set, TreeHaver tries these names in order:
+  - `tree-sitter`
+  - `libtree-sitter.so.0`
+  - `libtree-sitter.so`
+  - `libtree-sitter.dylib`
+  - `libtree-sitter.dll`
+
+#### Language Symbol Resolution
+
+When loading a language grammar, if you don't specify the `symbol:` parameter, TreeHaver resolves it in this precedence:
+
+1. **`TREE_SITTER_LANG_SYMBOL`**: Explicit symbol override
+2. Guessed from filename (e.g., `libtree-sitter-toml.so` → `tree_sitter_toml`)
+3. Default fallback (`tree_sitter_toml`)
+
+```bash
+export TREE_SITTER_LANG_SYMBOL=tree_sitter_toml
+```
+
+#### Language Library Paths
+
+For specific languages, you can set environment variables to point to grammar libraries:
+
+```bash
+export TREE_SITTER_TOML_PATH=/usr/local/lib/libtree-sitter-toml.so
+export TREE_SITTER_JSON_PATH=/usr/local/lib/libtree-sitter-json.so
+```
+
+#### JRuby-Specific: Java Backend JARs
+
+For the Java backend on JRuby:
+
+```bash
+export TREE_SITTER_JAVA_JARS_DIR=/path/to/java-tree-sitter/jars
+```
+
+### Language Registration
+
+Register languages once at application startup for convenient access:
+
+```ruby
+# Register a TOML grammar
+TreeHaver.register_language(
+  :toml,
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+  symbol: "tree_sitter_toml",  # optional, will be inferred if omitted
+)
+
+# Now you can use the convenient helper
+language = TreeHaver::Language.toml
+
+# Or still override path/symbol per-call
+language = TreeHaver::Language.toml(
+  path: "/custom/path/libtree-sitter-toml.so",
+)
+```
+
+### Grammar Discovery with GrammarFinder
+
+For libraries that need to automatically locate tree-sitter grammars (like the `*-merge` family of gems), TreeHaver provides the `GrammarFinder` utility class. It handles platform-aware grammar discovery without requiring language-specific code in TreeHaver itself.
+
+```ruby
+# Create a finder for any language
+finder = TreeHaver::GrammarFinder.new(:toml)
+
+# Check if the grammar is available
+if finder.available?
+  puts "TOML grammar found at: #{finder.find_library_path}"
+else
+  puts finder.not_found_message
+  # => "Tree-sitter toml grammar not found. Searched: /usr/lib/libtree-sitter-toml.so, ..."
+end
+
+# Register the language if available
+finder.register! if finder.available?
+
+# Now use the registered language
+language = TreeHaver::Language.toml
+```
+
+#### GrammarFinder Automatic Derivation
+
+Given just the language name, `GrammarFinder` automatically derives:
+
+| Property | Derived Value (for `:toml`) |
+|----------|----------------------------|
+| ENV var  | `TREE_SITTER_TOML_PATH` |
+| Library filename | `libtree-sitter-toml.so` (Linux) or `.dylib` (macOS) |
+| Symbol name | `tree_sitter_toml` |
+
+#### Search Order
+
+`GrammarFinder` searches for grammars in this order:
+
+1. **Environment variable**: `TREE_SITTER_<LANG>_PATH` (highest priority)
+2. **Extra paths**: Custom paths provided at initialization
+3. **System paths**: Common installation directories (`/usr/lib`, `/usr/local/lib`, `/opt/homebrew/lib`, etc.)
+
+#### Usage in *-merge Gems
+
+The `GrammarFinder` pattern enables clean integration in language-specific merge gems:
+
+```ruby
+# In toml-merge
+finder = TreeHaver::GrammarFinder.new(:toml)
+finder.register! if finder.available?
+
+# In json-merge
+finder = TreeHaver::GrammarFinder.new(:json)
+finder.register! if finder.available?
+
+# In bash-merge
+finder = TreeHaver::GrammarFinder.new(:bash)
+finder.register! if finder.available?
+```
+
+Each gem uses the same API—only the language name changes.
+
+#### Adding Custom Search Paths
+
+For non-standard installations, provide extra search paths:
+
+```ruby
+finder = TreeHaver::GrammarFinder.new(:toml, extra_paths: [
+  "/opt/custom/lib",
+  "/home/user/.local/lib",
+])
+```
+
+#### Debug Information
+
+Get detailed information about the grammar search:
+
+```ruby
+finder = TreeHaver::GrammarFinder.new(:toml)
+puts finder.search_info
+# => {
+#      language: :toml,
+#      env_var: "TREE_SITTER_TOML_PATH",
+#      env_value: nil,
+#      symbol: "tree_sitter_toml",
+#      library_filename: "libtree-sitter-toml.so",
+#      search_paths: ["/usr/lib/libtree-sitter-toml.so", ...],
+#      found_path: "/usr/lib/libtree-sitter-toml.so",
+#      available: true
+#    }
+```
+
+### Checking Capabilities
+
+Different backends may support different features:
+
+```ruby
+TreeHaver.capabilities
+# => { backend: :mri, query: true, bytes_field: true }
+# or
+# => { backend: :ffi, parse: true, query: false, bytes_field: true }
+```
+
+### Compatibility Mode
+
+For codebases migrating from `ruby_tree_sitter`, TreeHaver provides a compatibility shim:
+
+```ruby
+require "tree_haver/compat"
+
+# Now TreeSitter constants map to TreeHaver
+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.
+
+## 🔧 Basic Usage
+
+### Quick Start
+
+Here's a complete example of parsing TOML with TreeHaver:
+
+```ruby
+require "tree_haver"
+
+# Load a language grammar
+language = TreeHaver::Language.from_library(
+  "/usr/local/lib/libtree-sitter-toml.so",
+  symbol: "tree_sitter_toml",
+)
+
+# Create a parser
+parser = TreeHaver::Parser.new
+parser.language = language
+
+# Parse some source code
+source = <<~TOML
+  [package]
+  name = "my-app"
+  version = "1.0.0"
+TOML
+
+tree = parser.parse(source)
+
+# Access the root node
+root = tree.root_node
+puts "Root node type: #{root.type}"  # => "document"
+
+# Traverse the tree
+root.each do |child|
+  puts "Child type: #{child.type}"
+  child.each do |grandchild|
+    puts "  Grandchild type: #{grandchild.type}"
+  end
+end
+```
+
+### Using Language Registration
+
+For cleaner code, register languages at startup:
+
+```ruby
+# At application initialization
+TreeHaver.register_language(
+  :toml,
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+)
+
+TreeHaver.register_language(
+  :json,
+  path: "/usr/local/lib/libtree-sitter-json.so",
+)
+
+# Later in your code
+toml_language = TreeHaver::Language.toml
+json_language = TreeHaver::Language.json
+
+parser = TreeHaver::Parser.new
+parser.language = toml_language
+tree = parser.parse(toml_source)
+```
+
+### Parsing Different Languages
+
+TreeHaver works with any Tree-sitter grammar:
+
+```ruby
+# Parse Ruby code
+ruby_lang = TreeHaver::Language.from_library(
+  "/path/to/libtree-sitter-ruby.so",
+)
+parser = TreeHaver::Parser.new
+parser.language = ruby_lang
+tree = parser.parse("class Foo; end")
+
+# Parse JavaScript
+js_lang = TreeHaver::Language.from_library(
+  "/path/to/libtree-sitter-javascript.so",
+)
+parser.language = js_lang  # Reuse the same parser
+tree = parser.parse("const x = 42;")
+```
+
+### Walking the AST
+
+TreeHaver provides simple node traversal:
+
+```ruby
+tree = parser.parse(source)
+root = tree.root_node
+
+# Recursive tree walk
+def walk_tree(node, depth = 0)
+  puts "#{"  " * depth}#{node.type}"
+  node.each { |child| walk_tree(child, depth + 1) }
+end
+
+walk_tree(root)
+```
+
+### Incremental Parsing
+
+TreeHaver supports incremental parsing when using the MRI or Rust backends. This is a major performance optimization for editors and IDEs that need to re-parse on every keystroke.
+
+```ruby
+# Check if current backend supports incremental parsing
+if TreeHaver.capabilities[:incremental]
+  puts "Incremental parsing is available!"
+end
+
+# Initial parse
+parser = TreeHaver::Parser.new
+parser.language = language
+tree = parser.parse_string(nil, "x = 1")
+
+# User edits the source: "x = 1" -> "x = 42"
+# Mark the tree as edited (tell tree-sitter what changed)
+tree.edit(
+  start_byte: 4,           # edit starts at byte 4
+  old_end_byte: 5,         # old text "1" ended at byte 5
+  new_end_byte: 6,         # new text "42" ends at byte 6
+  start_point: {row: 0, column: 4},
+  old_end_point: {row: 0, column: 5},
+  new_end_point: {row: 0, column: 6},
+)
+
+# Re-parse incrementally - tree-sitter reuses unchanged nodes
+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 backend does 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.
+
+```ruby
+tree.supports_editing?  # => true if edit() is available
+```
+
+### Error Handling
+
+```ruby
+begin
+  language = TreeHaver::Language.from_library("/path/to/grammar.so")
+rescue TreeHaver::NotAvailable => e
+  puts "Failed to load grammar: #{e.message}"
+end
+
+# Check if a backend is available
+if TreeHaver.backend_module.nil?
+  puts "No TreeHaver backend is available!"
+  puts "Install ruby_tree_sitter (MRI) or ensure ffi gem and libtree-sitter are present"
+end
+```
+
+### Platform-Specific Examples
+
+#### MRI Ruby
+
+On MRI, TreeHaver uses `ruby_tree_sitter` by default:
+
+```ruby
+# Gemfile
+gem "tree_haver"
+gem "ruby_tree_sitter"  # MRI backend
+
+# Code - no changes needed, TreeHaver auto-selects MRI backend
+parser = TreeHaver::Parser.new
+```
+
+#### JRuby
+
+On JRuby, TreeHaver can use either the FFI backend or the Java backend:
+
+**Option 1: FFI Backend (simpler setup)**
+
+```ruby
+# Gemfile
+gem "tree_haver"
+gem "ffi"  # Required for FFI backend
+
+# Ensure libtree-sitter is installed on your system
+# On macOS with Homebrew:
+#   brew install tree-sitter
+
+# On Ubuntu/Debian:
+#   sudo apt-get install libtree-sitter0 libtree-sitter-dev
+
+# Code - TreeHaver auto-selects FFI backend on JRuby
+parser = TreeHaver::Parser.new
+```
+
+**Option 2: Java Backend (native JVM performance)**
+
+```bash
+# 1. Download java-tree-sitter JAR from Maven Central
+mkdir -p vendor/jars
+curl -fSL -o vendor/jars/jtreesitter-0.23.2.jar \
+  "https://repo1.maven.org/maven2/io/github/tree-sitter/jtreesitter/0.23.2/jtreesitter-0.23.2.jar"
+
+# 2. Set environment variables
+export CLASSPATH="$(pwd)/vendor/jars:$CLASSPATH"
+export LD_LIBRARY_PATH="/path/to/libtree-sitter/lib:$LD_LIBRARY_PATH"
+
+# 3. Run with JRuby (requires Java 22+ for Foreign Function API)
+JAVA_OPTS="--enable-native-access=ALL-UNNAMED" jruby your_script.rb
+```
+
+```ruby
+# Force Java backend
+TreeHaver.backend = :java
+
+# Check if Java backend is available
+if TreeHaver::Backends::Java.available?
+  puts "Java backend is ready!"
+  puts TreeHaver.capabilities
+  # => { backend: :java, parse: true, query: true, bytes_field: true, incremental: true }
+end
+```
+
+**⚠️ Java Backend Limitation: Symbol Resolution**
+
+The Java backend uses Java's Foreign Function & Memory (FFM) API which loads libraries in isolation. Unlike the system's dynamic linker (`dlopen`), FFM's `SymbolLookup.or()` chains symbol lookups but doesn't resolve dynamic library dependencies.
+
+This means grammar `.so` files with unresolved references to `libtree-sitter.so` symbols won't load correctly. Most grammars from luarocks, npm, or other sources have these dependencies.
+
+**Recommended approach for JRuby:** Use the **FFI backend**:
+
+```ruby
+# On JRuby, use FFI backend (recommended)
+TreeHaver.backend = :ffi
+```
+
+The FFI backend uses Ruby's FFI gem which relies on the system's dynamic linker, correctly resolving symbol dependencies between `libtree-sitter.so` and grammar libraries.
+
+The Java backend will work with:
+- Grammar JARs built specifically for java-tree-sitter (self-contained)
+- Grammar `.so` files that statically link tree-sitter
+
+#### TruffleRuby
+
+TruffleRuby can use either the MRI or FFI backend:
+
+```ruby
+# Use FFI backend (recommended)
+TreeHaver.backend = :ffi
+
+# Or try MRI backend if ruby_tree_sitter compiles on your TruffleRuby version
+TreeHaver.backend = :mri
+```
+
+### Advanced: Testing with Multiple Backends
+
+If you're developing a library that uses TreeHaver, you can test against different backends:
+
+```ruby
+# In your test setup
+RSpec.describe("MyParser") do
+  before do
+    TreeHaver.reset_backend!(to: :ffi)
+  end
+
+  after do
+    TreeHaver.reset_backend!(to: :auto)
+  end
+
+  it "parses correctly with FFI backend" do
+    # Your test code
+  end
+end
+```
+
+### Complete Real-World Example
+
+Here's a practical example that extracts package names from a TOML file:
+
+```ruby
+require "tree_haver"
+
+# Setup
+TreeHaver.register_language(
+  :toml,
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+)
+
+def extract_package_name(toml_content)
+  # Create parser
+  parser = TreeHaver::Parser.new
+  parser.language = TreeHaver::Language.toml
+
+  # Parse
+  tree = parser.parse(toml_content)
+  root = tree.root_node
+
+  # Find [package] table
+  root.each do |child|
+    next unless child.type == "table"
+
+    child.each do |table_elem|
+      if table_elem.type == "pair"
+        # Look for name = "..." pair
+        key = table_elem.each.first&.type
+        # In a real implementation, you'd extract the text value
+        # This is simplified for demonstration
+      end
+    end
+  end
+end
+
+# Usage
+toml = <<~TOML
+  [package]
+  name = "awesome-app"
+  version = "2.0.0"
+TOML
+
+package_name = extract_package_name(toml)
+```
+
+## 🦷 FLOSS Funding
+
+While kettle-rb tools are free software and will always be, the project would benefit immensely from some funding.
+Raising a monthly budget of... "dollars" would make the project more sustainable.
+
+We welcome both individual and corporate sponsors! We also offer a
+wide array of funding channels to account for your preferences
+(although currently [Open Collective][🖇osc] is our preferred funding platform).
+
+**If you're working in a company that's making significant use of kettle-rb tools we'd
+appreciate it if you suggest to your company to become a kettle-rb sponsor.**
+
+You can support the development of kettle-rb tools via
+[GitHub Sponsors][🖇sponsor],
+[Liberapay][⛳liberapay],
+[PayPal][🖇paypal],
+[Open Collective][🖇osc]
+and [Tidelift][🏙️entsup-tidelift].
+
+| 📍 NOTE                                                                                                                                                                                                              |
+|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| If doing a sponsorship in the form of donation is problematic for your company <br/> from an accounting standpoint, we'd recommend the use of Tidelift, <br/> where you can get a support-like subscription instead. |
+
+### Open Collective for Individuals
+
+Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/kettle-rb#backer)]
+
+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
+
+Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)]
+
+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
+
+### Another way to support open-source
+
+I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small.  Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions.  I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈‍ cats).
+
+If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in `bundle fund`.
+
+I’m developing a new library, [floss_funding][🖇floss-funding-gem], designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.
+
+**[Floss-Funding.dev][🖇floss-funding.dev]: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags**
+
+[![OpenCollective Backers][🖇osc-backers-i]][🖇osc-backers] [![OpenCollective Sponsors][🖇osc-sponsors-i]][🖇osc-sponsors] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS efforts using Patreon][🖇patreon-img]][🖇patreon]
+
+## 🔐 Security
+
+See [SECURITY.md][🔐security].
+
+## 🤝 Contributing
+
+If you need some ideas of where to help, you could work on adding more code coverage,
+or if it is already 💯 (see [below](#code-coverage)) check [reek](REEK), [issues][🤝gh-issues], or [PRs][🤝gh-pulls],
+or use the gem and think about how it could be better.
+
+We [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] so if you make changes, remember to update it.
+
+See [CONTRIBUTING.md][🤝contributing] for more detailed instructions.
+
+### 🚀 Release Instructions
+
+See [CONTRIBUTING.md][🤝contributing].
+
+### Code Coverage
+
+[![Coverage Graph][🏀codecov-g]][🏀codecov]
+
+[![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls]
+
+[![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov]
+
+### 🪇 Code of Conduct
+
+Everyone interacting with this project's codebases, issue trackers,
+chat rooms and mailing lists agrees to follow the [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct].
+
+## 🌈 Contributors
+
+[![Contributors][🖐contributors-img]][🖐contributors]
+
+Made with [contributors-img][🖐contrib-rocks].
+
+Also see GitLab Contributors: [https://gitlab.com/kettle-rb/tree_haver/-/graphs/main][🚎contributors-gl]
+
+<details>
+    <summary>⭐️ Star History</summary>
+
+<a href="https://star-history.com/#kettle-rb/tree_haver&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kettle-rb/tree_haver&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kettle-rb/tree_haver&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kettle-rb/tree_haver&type=Date" />
+ </picture>
+</a>
+
+</details>
+
+## 📌 Versioning
+
+This Library adheres to [![Semantic Versioning 2.0.0][📌semver-img]][📌semver].
+Violations of this scheme should be reported as bugs.
+Specifically, if a minor or patch version is released that breaks backward compatibility,
+a new version should be immediately released that restores compatibility.
+Breaking changes to the public API will only be introduced with new major versions.
+
+> dropping support for a platform is both obviously and objectively a breaking change <br/>
+>—Jordan Harband ([@ljharb](https://github.com/ljharb), maintainer of SemVer) [in SemVer issue 716][📌semver-breaking]
+
+I understand that policy doesn't work universally ("exceptions to every rule!"),
+but it is the policy here.
+As such, in many cases it is good to specify a dependency on this library using
+the [Pessimistic Version Constraint][📌pvc] with two digits of precision.
+
+For example:
+
+```ruby
+spec.add_dependency("tree_haver", "~> 1.0")
+```
+
+<details markdown="1">
+<summary>📌 Is "Platform Support" part of the public API? More details inside.</summary>
+
+SemVer should, IMO, but doesn't explicitly, say that dropping support for specific Platforms
+is a *breaking change* to an API, and for that reason the bike shedding is endless.
+
+To get a better understanding of how SemVer is intended to work over a project's lifetime,
+read this article from the creator of SemVer:
+
+- ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
+
+</details>
+
+See [CHANGELOG.md][📌changelog] for a list of releases.
+
+## 📄 License
+
+The gem is available as open source under the terms of
+the [MIT License][📄license] [![License: MIT][📄license-img]][📄license-ref].
+See [LICENSE.txt][📄license] for the official [Copyright Notice][📄copyright-notice-explainer].
+
+### © Copyright
+
+<ul>
+    <li>
+        Copyright (c) 2025 Peter H. Boling, of
+        <a href="https://discord.gg/3qme4XHNKN">
+            Galtzo.com
+            <picture>
+              <img src="https://logos.galtzo.com/assets/images/galtzo-floss/avatar-128px-blank.svg" alt="Galtzo.com Logo (Wordless) by Aboling0, CC BY-SA 4.0" width="24">
+            </picture>
+        </a>, and tree_haver contributors.
+    </li>
+</ul>
+
+## 🤑 A request for help
+
+Maintainers have teeth and need to pay their dentists.
+After getting laid off in an RIF in March, and encountering difficulty finding a new one,
+I began spending most of my time building open source tools.
+I'm hoping to be able to pay for my kids' health insurance this month,
+so if you value the work I am doing, I need your support.
+Please consider sponsoring me or the project.
+
+To join the community or get help 👇️ Join the Discord.
+
+[![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite]
+
+To say "thanks!" ☝️ Join the Discord or 👇️ send money.
+
+[![Sponsor kettle-rb/tree_haver on Open Source Collective][🖇osc-all-bottom-img]][🖇osc] 💌 [![Sponsor me on GitHub Sponsors][🖇sponsor-bottom-img]][🖇sponsor] 💌 [![Sponsor me on Liberapay][⛳liberapay-bottom-img]][⛳liberapay] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal]
+
+### Please give the project a star ⭐ ♥.
+
+Thanks for RTFM. ☺️
+
+[⛳liberapay-img]: https://img.shields.io/liberapay/goal/pboling.svg?logo=liberapay&color=a51611&style=flat
+[⛳liberapay-bottom-img]: https://img.shields.io/liberapay/goal/pboling.svg?style=for-the-badge&logo=liberapay&color=a51611
+[⛳liberapay]: https://liberapay.com/pboling/donate
+[🖇osc-all-img]: https://img.shields.io/opencollective/all/kettle-rb
+[🖇osc-sponsors-img]: https://img.shields.io/opencollective/sponsors/kettle-rb
+[🖇osc-backers-img]: https://img.shields.io/opencollective/backers/kettle-rb
+[🖇osc-backers]: https://opencollective.com/kettle-rb#backer
+[🖇osc-backers-i]: https://opencollective.com/kettle-rb/backers/badge.svg?style=flat
+[🖇osc-sponsors]: https://opencollective.com/kettle-rb#sponsor
+[🖇osc-sponsors-i]: https://opencollective.com/kettle-rb/sponsors/badge.svg?style=flat
+[🖇osc-all-bottom-img]: https://img.shields.io/opencollective/all/kettle-rb?style=for-the-badge
+[🖇osc-sponsors-bottom-img]: https://img.shields.io/opencollective/sponsors/kettle-rb?style=for-the-badge
+[🖇osc-backers-bottom-img]: https://img.shields.io/opencollective/backers/kettle-rb?style=for-the-badge
+[🖇osc]: https://opencollective.com/kettle-rb
+[🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github
+[🖇sponsor-bottom-img]: https://img.shields.io/badge/Sponsor_Me!-pboling-blue?style=for-the-badge&logo=github
+[🖇sponsor]: https://github.com/sponsors/pboling
+[🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat
+[🖇polar]: https://polar.sh/pboling
+[🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat
+[🖇kofi]: https://ko-fi.com/O5O86SNP4
+[🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat
+[🖇patreon]: https://patreon.com/galtzo
+[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat
+[🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff
+[🖇buyme]: https://www.buymeacoffee.com/pboling
+[🖇paypal-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal
+[🖇paypal-bottom-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=for-the-badge&logo=paypal&color=0A0A0A
+[🖇paypal]: https://www.paypal.com/paypalme/peterboling
+[🖇floss-funding.dev]: https://floss-funding.dev
+[🖇floss-funding-gem]: https://github.com/galtzo-floss/floss_funding
+[✉️discord-invite]: https://discord.gg/3qme4XHNKN
+[✉️discord-invite-img-ftb]: https://img.shields.io/discord/1373797679469170758?style=for-the-badge&logo=discord
+[✉️ruby-friends-img]: https://img.shields.io/badge/daily.dev-%F0%9F%92%8E_Ruby_Friends-0A0A0A?style=for-the-badge&logo=dailydotdev&logoColor=white
+[✉️ruby-friends]: https://app.daily.dev/squads/rubyfriends
+
+[✇bundle-group-pattern]: https://gist.github.com/pboling/4564780
+[⛳️gem-namespace]: https://github.com/kettle-rb/tree_haver
+[⛳️namespace-img]: https://img.shields.io/badge/namespace-TreeHaver-3C2D2D.svg?style=square&logo=ruby&logoColor=white
+[⛳️gem-name]: https://bestgems.org/gems/tree_haver
+[⛳️name-img]: https://img.shields.io/badge/name-tree__haver-3C2D2D.svg?style=square&logo=rubygems&logoColor=red
+[⛳️tag-img]: https://img.shields.io/github/tag/kettle-rb/tree_haver.svg
+[⛳️tag]: http://github.com/kettle-rb/tree_haver/releases
+[🚂maint-blog]: http://www.railsbling.com/tags/tree_haver
+[🚂maint-blog-img]: https://img.shields.io/badge/blog-railsbling-0093D0.svg?style=for-the-badge&logo=rubyonrails&logoColor=orange
+[🚂maint-contact]: http://www.railsbling.com/contact
+[🚂maint-contact-img]: https://img.shields.io/badge/Contact-Maintainer-0093D0.svg?style=flat&logo=rubyonrails&logoColor=red
+[💖🖇linkedin]: http://www.linkedin.com/in/peterboling
+[💖🖇linkedin-img]: https://img.shields.io/badge/PeterBoling-LinkedIn-0B66C2?style=flat&logo=newjapanprowrestling
+[💖✌️wellfound]: https://wellfound.com/u/peter-boling
+[💖✌️wellfound-img]: https://img.shields.io/badge/peter--boling-orange?style=flat&logo=wellfound
+[💖💲crunchbase]: https://www.crunchbase.com/person/peter-boling
+[💖💲crunchbase-img]: https://img.shields.io/badge/peter--boling-purple?style=flat&logo=crunchbase
+[💖🐘ruby-mast]: https://ruby.social/@galtzo
+[💖🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https://ruby.social&style=flat&logo=mastodon&label=Ruby%20@galtzo
+[💖🦋bluesky]: https://bsky.app/profile/galtzo.com
+[💖🦋bluesky-img]: https://img.shields.io/badge/@galtzo.com-0285FF?style=flat&logo=bluesky&logoColor=white
+[💖🌳linktree]: https://linktr.ee/galtzo
+[💖🌳linktree-img]: https://img.shields.io/badge/galtzo-purple?style=flat&logo=linktree
+[💖💁🏼‍♂️devto]: https://dev.to/galtzo
+[💖💁🏼‍♂️devto-img]: https://img.shields.io/badge/dev.to-0A0A0A?style=flat&logo=devdotto&logoColor=white
+[💖💁🏼‍♂️aboutme]: https://about.me/peter.boling
+[💖💁🏼‍♂️aboutme-img]: https://img.shields.io/badge/about.me-0A0A0A?style=flat&logo=aboutme&logoColor=white
+[💖🧊berg]: https://codeberg.org/pboling
+[💖🐙hub]: https://github.org/pboling
+[💖🛖hut]: https://sr.ht/~galtzo/
+[💖🧪lab]: https://gitlab.com/pboling
+[👨🏼‍🏫expsup-upwork]: https://www.upwork.com/freelancers/~014942e9b056abdf86?mp_source=share
+[👨🏼‍🏫expsup-upwork-img]: https://img.shields.io/badge/UpWork-13544E?style=for-the-badge&logo=Upwork&logoColor=white
+[👨🏼‍🏫expsup-codementor]: https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github
+[👨🏼‍🏫expsup-codementor-img]: https://img.shields.io/badge/CodeMentor-Get_Help-1abc9c?style=for-the-badge&logo=CodeMentor&logoColor=white
+[🏙️entsup-tidelift]: https://tidelift.com/subscription/pkg/rubygems-tree_haver?utm_source=rubygems-tree_haver&utm_medium=referral&utm_campaign=readme
+[🏙️entsup-tidelift-img]: https://img.shields.io/badge/Tidelift_and_Sonar-Enterprise_Support-FD3456?style=for-the-badge&logo=sonar&logoColor=white
+[🏙️entsup-tidelift-sonar]: https://blog.tidelift.com/tidelift-joins-sonar
+[💁🏼‍♂️peterboling]: http://www.peterboling.com
+[🚂railsbling]: http://www.railsbling.com
+[📜src-gl-img]: https://img.shields.io/badge/GitLab-FBA326?style=for-the-badge&logo=Gitlab&logoColor=orange
+[📜src-gl]: https://gitlab.com/kettle-rb/tree_haver/
+[📜src-cb-img]: https://img.shields.io/badge/CodeBerg-4893CC?style=for-the-badge&logo=CodeBerg&logoColor=blue
+[📜src-cb]: https://codeberg.org/kettle-rb/tree_haver
+[📜src-gh-img]: https://img.shields.io/badge/GitHub-238636?style=for-the-badge&logo=Github&logoColor=green
+[📜src-gh]: https://github.com/kettle-rb/tree_haver
+[📜docs-cr-rd-img]: https://img.shields.io/badge/RubyDoc-Current_Release-943CD2?style=for-the-badge&logo=readthedocs&logoColor=white
+[📜docs-head-rd-img]: https://img.shields.io/badge/YARD_on_Galtzo.com-HEAD-943CD2?style=for-the-badge&logo=readthedocs&logoColor=white
+[📜gl-wiki]: https://gitlab.com/kettle-rb/tree_haver/-/wikis/home
+[📜gh-wiki]: https://github.com/kettle-rb/tree_haver/wiki
+[📜gl-wiki-img]: https://img.shields.io/badge/wiki-examples-943CD2.svg?style=for-the-badge&logo=gitlab&logoColor=white
+[📜gh-wiki-img]: https://img.shields.io/badge/wiki-examples-943CD2.svg?style=for-the-badge&logo=github&logoColor=white
+[👽dl-rank]: https://bestgems.org/gems/tree_haver
+[👽dl-ranki]: https://img.shields.io/gem/rd/tree_haver.svg
+[👽oss-help]: https://www.codetriage.com/kettle-rb/tree_haver
+[👽oss-helpi]: https://www.codetriage.com/kettle-rb/tree_haver/badges/users.svg
+[👽version]: https://bestgems.org/gems/tree_haver
+[👽versioni]: https://img.shields.io/gem/v/tree_haver.svg
+[🏀qlty-mnt]: https://qlty.sh/gh/kettle-rb/projects/tree_haver
+[🏀qlty-mnti]: https://qlty.sh/gh/kettle-rb/projects/tree_haver/maintainability.svg
+[🏀qlty-cov]: https://qlty.sh/gh/kettle-rb/projects/tree_haver/metrics/code?sort=coverageRating
+[🏀qlty-covi]: https://qlty.sh/gh/kettle-rb/projects/tree_haver/coverage.svg
+[🏀codecov]: https://codecov.io/gh/kettle-rb/tree_haver
+[🏀codecovi]: https://codecov.io/gh/kettle-rb/tree_haver/graph/badge.svg
+[🏀coveralls]: https://coveralls.io/github/kettle-rb/tree_haver?branch=main
+[🏀coveralls-img]: https://coveralls.io/repos/github/kettle-rb/tree_haver/badge.svg?branch=main
+[🖐codeQL]: https://github.com/kettle-rb/tree_haver/security/code-scanning
+[🖐codeQL-img]: https://github.com/kettle-rb/tree_haver/actions/workflows/codeql-analysis.yml/badge.svg
+[🚎2-cov-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/coverage.yml
+[🚎2-cov-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/coverage.yml/badge.svg
+[🚎3-hd-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/heads.yml
+[🚎3-hd-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/heads.yml/badge.svg
+[🚎5-st-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/style.yml
+[🚎5-st-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/style.yml/badge.svg
+[🚎6-s-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/supported.yml
+[🚎6-s-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/supported.yml/badge.svg
+[🚎9-t-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/truffle.yml
+[🚎9-t-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/truffle.yml/badge.svg
+[🚎11-c-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/current.yml
+[🚎11-c-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/current.yml/badge.svg
+[🚎12-crh-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/dep-heads.yml
+[🚎12-crh-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/dep-heads.yml/badge.svg
+[🚎13-🔒️-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/locked_deps.yml
+[🚎13-🔒️-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/locked_deps.yml/badge.svg
+[🚎14-🔓️-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/unlocked_deps.yml
+[🚎14-🔓️-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/unlocked_deps.yml/badge.svg
+[🚎15-🪪-wf]: https://github.com/kettle-rb/tree_haver/actions/workflows/license-eye.yml
+[🚎15-🪪-wfi]: https://github.com/kettle-rb/tree_haver/actions/workflows/license-eye.yml/badge.svg
+[💎ruby-3.2i]: https://img.shields.io/badge/Ruby-3.2-CC342D?style=for-the-badge&logo=ruby&logoColor=white
+[💎ruby-3.3i]: https://img.shields.io/badge/Ruby-3.3-CC342D?style=for-the-badge&logo=ruby&logoColor=white
+[💎ruby-c-i]: https://img.shields.io/badge/Ruby-current-CC342D?style=for-the-badge&logo=ruby&logoColor=green
+[💎ruby-headi]: https://img.shields.io/badge/Ruby-HEAD-CC342D?style=for-the-badge&logo=ruby&logoColor=blue
+[💎truby-23.1i]: https://img.shields.io/badge/Truffle_Ruby-23.1-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
+[💎truby-c-i]: https://img.shields.io/badge/Truffle_Ruby-current-34BCB1?style=for-the-badge&logo=ruby&logoColor=green
+[💎truby-headi]: https://img.shields.io/badge/Truffle_Ruby-HEAD-34BCB1?style=for-the-badge&logo=ruby&logoColor=blue
+[💎jruby-c-i]: https://img.shields.io/badge/JRuby-current-FBE742?style=for-the-badge&logo=ruby&logoColor=green
+[💎jruby-headi]: https://img.shields.io/badge/JRuby-HEAD-FBE742?style=for-the-badge&logo=ruby&logoColor=blue
+[🤝gh-issues]: https://github.com/kettle-rb/tree_haver/issues
+[🤝gh-pulls]: https://github.com/kettle-rb/tree_haver/pulls
+[🤝gl-issues]: https://gitlab.com/kettle-rb/tree_haver/-/issues
+[🤝gl-pulls]: https://gitlab.com/kettle-rb/tree_haver/-/merge_requests
+[🤝cb-issues]: https://codeberg.org/kettle-rb/tree_haver/issues
+[🤝cb-pulls]: https://codeberg.org/kettle-rb/tree_haver/pulls
+[🤝cb-donate]: https://donate.codeberg.org/
+[🤝contributing]: CONTRIBUTING.md
+[🏀codecov-g]: https://codecov.io/gh/kettle-rb/tree_haver/graphs/tree.svg
+[🖐contrib-rocks]: https://contrib.rocks
+[🖐contributors]: https://github.com/kettle-rb/tree_haver/graphs/contributors
+[🖐contributors-img]: https://contrib.rocks/image?repo=kettle-rb/tree_haver
+[🚎contributors-gl]: https://gitlab.com/kettle-rb/tree_haver/-/graphs/main
+[🪇conduct]: CODE_OF_CONDUCT.md
+[🪇conduct-img]: https://img.shields.io/badge/Contributor_Covenant-2.1-259D6C.svg
+[📌pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
+[📌semver]: https://semver.org/spec/v2.0.0.html
+[📌semver-img]: https://img.shields.io/badge/semver-2.0.0-259D6C.svg?style=flat
+[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139
+[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
+[📌changelog]: CHANGELOG.md
+[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
+[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-34495e.svg?style=flat
+[📌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-0.501-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
+[📄license]: LICENSE.txt
+[📄license-ref]: https://opensource.org/licenses/MIT
+[📄license-img]: https://img.shields.io/badge/License-MIT-259D6C.svg
+[📄license-compat]: https://dev.to/galtzo/how-to-check-license-compatibility-41h0
+[📄license-compat-img]: https://img.shields.io/badge/Apache_Compatible:_Category_A-%E2%9C%93-259D6C.svg?style=flat&logo=Apache
+[📄ilo-declaration]: https://www.ilo.org/declaration/lang--en/index.htm
+[📄ilo-declaration-img]: https://img.shields.io/badge/ILO_Fundamental_Principles-✓-259D6C.svg?style=flat
+[🚎yard-current]: http://rubydoc.info/gems/tree_haver
+[🚎yard-head]: https://tree-haver.galtzo.com
+[💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums
+[💎SHA_checksums]: https://gitlab.com/kettle-rb/tree_haver/-/tree/main/checksums
+[💎rlts]: https://github.com/rubocop-lts/rubocop-lts
+[💎rlts-img]: https://img.shields.io/badge/code_style_&_linting-rubocop--lts-34495e.svg?plastic&logo=ruby&logoColor=white
+[💎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/