tree_haver 1.0.0 → 3.0.0

data/README.md

@@ -54,20 +54,24 @@
 
 ## 🌻 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/) 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 |
+| 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 |
 
-**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.
+**Write once, run anywhere.** 
+
+**Learn once, write 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
@@ -76,7 +80,7 @@ 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)
+# - MRI → ruby_tree_sitter (C extensions)
 # - JRuby → FFI (system's libtree-sitter)
 # - TruffleRuby → FFI or MRI backend
 ```
@@ -90,15 +94,84 @@ tree = parser.parse(source_code)
     - **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)
 - **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**: 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
+- **Minimal API Surface**: Simple, focused API that covers the most common tree-sitter use cases
+
+### Backend Requirements
+
+TreeHaver has minimal dependencies and automatically selects the best backend for your Ruby implementation. Each backend has specific version requirements:
+
+#### MRI Backend (ruby_tree_sitter, C extensions)
+
+**Requires `ruby_tree_sitter` v2.0+**
+
+In ruby_tree_sitter v2.0, all TreeSitter exceptions were changed to inherit from `Exception` (not `StandardError`). This was an intentional breaking change made for thread-safety and signal handling reasons.
+
+**Exception Mapping**: TreeHaver catches `TreeSitter::TreeSitterError` and its subclasses, converting them to `TreeHaver::NotAvailable` while preserving the original error message. This provides a consistent exception API across all backends:
+
+| ruby_tree_sitter Exception          | TreeHaver Exception        | When It Occurs                                 |
+|-------------------------------------|----------------------------|------------------------------------------------|
+| `TreeSitter::ParserNotFoundError`   | `TreeHaver::NotAvailable`  | Parser library file cannot be loaded           |
+| `TreeSitter::LanguageLoadError`     | `TreeHaver::NotAvailable`  | Language symbol loads but returns nothing      |
+| `TreeSitter::SymbolNotFoundError`   | `TreeHaver::NotAvailable`  | Symbol not found in library                    |
+| `TreeSitter::ParserVersionError`    | `TreeHaver::NotAvailable`  | Parser version incompatible with tree-sitter   |
+| `TreeSitter::QueryCreationError`    | `TreeHaver::NotAvailable`  | Query creation fails                           |
+
+```ruby
+# Add to your Gemfile for MRI backend
+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.
+
+```ruby
+# Add to your Gemfile for Rust backend
+gem "tree_stump", github: "pboling/tree_stump", branch: "tree_haver"
+```
+
+#### FFI Backend
+
+Requires the `ffi` gem and a system installation of `libtree-sitter`:
+
+```ruby
+# Add to your Gemfile for FFI backend
+gem "ffi", ">= 1.15", "< 2.0"
+```
+
+```bash
+# Install libtree-sitter on your system:
+# macOS
+brew install tree-sitter
+
+# Ubuntu/Debian
+apt-get install libtree-sitter0 libtree-sitter-dev
+
+# Fedora
+dnf install tree-sitter tree-sitter-devel
+```
+
+#### Citrus Backend
+
+Pure Ruby parser with no native dependencies:
+
+```ruby
+# Add to your Gemfile for Citrus backend
+gem "citrus", "~> 3.0"
+```
+
+#### Java Backend (JRuby only)
+
+No additional dependencies required beyond grammar JARs built for java-tree-sitter.
 
 ### 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:
+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
@@ -106,25 +179,28 @@ 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.
 
-### 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+           |
+### Comparison with Other Ruby AST / Parser Bindings
+
+| Feature                   | [tree_haver] (this gem)                | [ruby_tree_sitter] | [tree_stump]   | [citrus]    |
+|---------------------------|----------------------------------------|--------------------|----------------|-------------|
+| **MRI Ruby**              | ✅ Yes                                  | ✅ Yes              | ✅ Yes          | ✅ Yes       |
+| **JRuby**                 | ✅ Yes (FFI, Java, or Citrus backend)   | ❌ No               | ❌ No           | ✅ Yes       |
+| **TruffleRuby**           | ✅ Yes (FFI or Citrus)                  | ❌ No               | ❓ Unknown      | ✅ Yes       |
+| **Backend**               | Multi (MRI C, Rust, FFI, Java, Citrus) | C extension only   | Rust extension | Pure Ruby   |
+| **Incremental Parsing**   | ✅ Via MRI C/Rust/Java backend          | ✅ Yes              | ✅ Yes          | ❌ No        |
+| **Query API**             | ⚡ Via MRI/Rust/Java backend            | ✅ Yes              | ✅ Yes          | ❌ No        |
+| **Grammar Discovery**     | ✅ Built-in `GrammarFinder`             | ❌ Manual           | ❌ Manual       | ❌ Manual    |
+| **Security Validations**  | ✅ `PathValidator`                      | ❌ No               | ❌ No           | ❌ No        |
+| **Language Registration** | ✅ Thread-safe registry                 | ❌ No               | ❌ No           | ❌ No        |
+| **Native Performance**    | ⚡ Backend-dependent                    | ✅ Native C         | ✅ Native Rust  | ❌ Pure Ruby |
+| **Precompiled Binaries**  | ⚡ Via Rust backend                     | ✅ Yes              | ✅ Yes          | ✅ Pure Ruby |
+| **Zero Native Deps**      | ⚡ Via Citrus backend                   | ❌ No               | ❌ No           | ✅ Yes       |
+| **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
+[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.
 
@@ -135,6 +211,7 @@ TreeHaver solves these problems by providing a unified API that automatically se
 #### 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
@@ -142,39 +219,48 @@ TreeHaver solves these problems by providing a unified API that automatically se
 - 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
 
+**Choose citrus directly when:**
+
+- You need zero native dependencies (pure Ruby)
+- You're using a Citrus grammar (not tree-sitter grammars)
+- Performance is less critical than portability
+- You don't need TreeHaver's unified API
+
 ## 💡 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]                                                                                          |
+| 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]                                                                   |
+| 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 💚             |
-|------------------------------------------------|--------------------------------------------------------|
+| 🚚 _Amazing_ test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚               |
+| ---------------------------------------------- | -------------------------------------------------------- |
 | 👟 Check it out!                               | ✨ [github.com/appraisal-rb/appraisal2][💎appraisal2] ✨ |
 
 ### Federated DVCS
@@ -183,9 +269,9 @@ Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRu
   <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 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] |
 
@@ -206,7 +292,7 @@ The maintainers of this and thousands of other packages are working with Tidelif
 
 - 💡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
+- 💡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:
 
@@ -245,7 +331,7 @@ Add my public key (if you haven’t already, expires 2045-04-29) as a trusted ce
 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:
+You only need to do that once. Then proceed to install with:
 
 ```console
 gem install tree_haver -P HighSecurity
@@ -267,6 +353,108 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ## ⚙️ Configuration
 
+### Available Backends
+
+TreeHaver supports multiple parsing backends, each with different trade-offs. The `auto` backend automatically selects the best available option.
+
+| 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) |
+| **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
+
+**Known Issues:**
+- *MRI + Bash: ABI incompatibility (use FFI instead)
+- *Rust + Bash: Version mismatch (use FFI instead)
+
+**Backend Requirements:**
+
+```ruby
+# MRI Backend
+gem 'ruby_tree_sitter'
+
+# Rust Backend  
+gem 'tree_stump'
+
+# FFI Backend
+gem 'ffi'
+
+# Citrus Backend
+gem 'citrus'
+# Plus grammar gems: toml-rb, dhall, finitio, etc.
+```
+
+**Force Specific Backend:**
+
+```ruby
+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 = :citrus # Force Citrus backend
+TreeHaver.backend = :auto   # Auto-select (default)
+```
+
+**Block-based Backend Switching:**
+
+Use `with_backend` to temporarily switch backends for a specific block of code.
+This is thread-safe and supports nesting—the previous backend is automatically
+restored when the block exits (even if an exception is raised).
+
+```ruby
+# Temporarily use a specific backend
+TreeHaver.with_backend(:mri) do
+  parser = TreeHaver::Parser.new
+  tree = parser.parse(source)
+  # All operations in this block use the MRI backend
+end
+# Backend is restored to its previous value here
+
+# Nested blocks work correctly
+TreeHaver.with_backend(:rust) do
+  # Uses :rust
+  TreeHaver.with_backend(:citrus) do
+    # Uses :citrus
+    parser = TreeHaver::Parser.new
+  end
+  # Back to :rust
+end
+# Back to original backend
+```
+
+This is particularly useful for:
+
+- **Testing**: Test the same code with different backends
+- **Performance comparison**: Benchmark different backends
+- **Fallback scenarios**: Try one backend, fall back to another
+- **Thread isolation**: Each thread can use a different backend safely
+
+```ruby
+# Example: Testing with multiple backends
+[:mri, :rust, :citrus].each do |backend_name|
+  TreeHaver.with_backend(backend_name) do
+    parser = TreeHaver::Parser.new
+    result = parser.parse(source)
+    puts "#{backend_name}: #{result.root_node.type}"
+  end
+end
+```
+
+**Check Backend Capabilities:**
+
+```ruby
+TreeHaver.backend              # => :ffi
+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.
+
 ### Security Considerations
 
 **⚠️ Loading shared libraries (.so/.dylib/.dll) executes arbitrary native code.**
@@ -359,15 +547,18 @@ TreeHaver automatically selects the best backend for your Ruby implementation, b
 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)
+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)
+TreeHaver.backend = :citrus  # Use Citrus pure Ruby parser
+                             # NOTE: Portable, all Ruby implementations
+                             # CAVEAT: few major language grammars, but many esoteric grammars
 ```
 
-**Auto-selection priority on MRI:** MRI → Rust → FFI
+**Auto-selection priority on MRI:** MRI → Rust → FFI → Citrus
 
 You can also set the backend via environment variable:
 
@@ -384,6 +575,7 @@ TreeHaver recognizes several environment variables for configuration:
 #### 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"
@@ -399,11 +591,12 @@ TreeHaver recognizes several environment variables for configuration:
   ```
 
 If not set, TreeHaver tries these names in order:
-  - `tree-sitter`
-  - `libtree-sitter.so.0`
-  - `libtree-sitter.so`
-  - `libtree-sitter.dylib`
-  - `libtree-sitter.dll`
+
+- `tree-sitter`
+- `libtree-sitter.so.0`
+- `libtree-sitter.so`
+- `libtree-sitter.dylib`
+- `libtree-sitter.dll`
 
 #### Language Symbol Resolution
 
@@ -468,7 +661,7 @@ 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, ..."
+  # => "tree-sitter toml grammar not found. Searched: /usr/lib/libtree-sitter-toml.so, ..."
 end
 
 # Register the language if available
@@ -482,11 +675,11 @@ language = TreeHaver::Language.toml
 
 Given just the language name, `GrammarFinder` automatically derives:
 
-| Property | Derived Value (for `:toml`) |
-|----------|----------------------------|
-| ENV var  | `TREE_SITTER_TOML_PATH` |
+| 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` |
+| Symbol name      | `tree_sitter_toml`                                   |
 
 #### Search Order
 
@@ -496,7 +689,7 @@ Given just the language name, `GrammarFinder` automatically derives:
 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
+#### Usage in \*-merge Gems
 
 The `GrammarFinder` pattern enables clean integration in language-specific merge gems:
 
@@ -555,6 +748,8 @@ TreeHaver.capabilities
 # => { backend: :mri, query: true, bytes_field: true }
 # or
 # => { backend: :ffi, parse: true, query: false, bytes_field: true }
+# or
+# => { backend: :citrus, parse: true, query: false, bytes_field: false }
 ```
 
 ### Compatibility Mode
@@ -570,6 +765,64 @@ 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`.**
+
+This means exception handling behaves **differently** between the two:
+
+| 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) |
+
+**Example showing the difference:**
+
+```ruby
+# With real ruby_tree_sitter v2+
+begin
+  TreeSitter::Language.load("missing", "/nonexistent.so")
+rescue => e
+  puts "Caught!"  # Never reached - TreeSitter errors inherit Exception
+end
+
+# With TreeHaver compat mode
+require "tree_haver/compat"
+begin
+  TreeSitter::Language.load("missing", "/nonexistent.so")  # Actually TreeHaver
+rescue => e
+  puts "Caught!"  # WILL be reached - TreeHaver errors inherit StandardError
+end
+```
+
+**To write compatible exception handling:**
+
+```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
+
+# Option 2: Use TreeHaver API directly (recommended)
+begin
+  TreeHaver::Language.from_library(...)
+rescue TreeHaver::NotAvailable => e  # TreeHaver's unified exception
+  # Clear and consistent when using TreeHaver
+end
+```
+
+**Why TreeHaver uses StandardError:**
+
+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
+
+See `lib/tree_haver/compat.rb` for detailed documentation.
+
 ## 🔧 Basic Usage
 
 ### Quick Start
@@ -636,9 +889,41 @@ parser.language = toml_language
 tree = parser.parse(toml_source)
 ```
 
+#### Flexible Language Names
+
+The `name` parameter in `register_language` is an arbitrary identifier you choose—it doesn't
+need to match the actual language name. The actual grammar identity comes from the `path`
+and `symbol` parameters (for tree-sitter) or `grammar_module` (for Citrus).
+
+This flexibility is useful for:
+
+- **Aliasing**: Register the same grammar under multiple names
+- **Versioning**: Register different grammar versions (e.g., `:ruby_2`, `:ruby_3`)
+- **Testing**: Use unique names to avoid collisions between tests
+- **Context-specific naming**: Use names that make sense for your application
+
+```ruby
+# Register the same TOML grammar under different names for different purposes
+TreeHaver.register_language(
+  :config_parser,  # Custom name for your app
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+  symbol: "tree_sitter_toml",
+)
+
+TreeHaver.register_language(
+  :toml_v1,  # Version-specific name
+  path: "/usr/local/lib/libtree-sitter-toml.so",
+  symbol: "tree_sitter_toml",
+)
+
+# Use your custom names
+config_lang = TreeHaver::Language.config_parser
+versioned_lang = TreeHaver::Language.toml_v1
+```
+
 ### Parsing Different Languages
 
-TreeHaver works with any Tree-sitter grammar:
+TreeHaver works with any tree-sitter grammar:
 
 ```ruby
 # Parse Ruby code
@@ -704,7 +989,7 @@ 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 backend does 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`) 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.
 
@@ -724,7 +1009,7 @@ 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"
+  puts "Install ruby_tree_sitter (MRI), ffi gem with libtree-sitter, or citrus gem"
 end
 ```
 
@@ -745,9 +1030,9 @@ parser = TreeHaver::Parser.new
 
 #### JRuby
 
-On JRuby, TreeHaver can use either the FFI backend or the Java backend:
+On JRuby, TreeHaver can use the FFI backend, Java backend, or Citrus backend:
 
-**Option 1: FFI Backend (simpler setup)**
+**Option 1: FFI Backend (recommended for tree-sitter grammars)**
 
 ```ruby
 # Gemfile
@@ -809,38 +1094,135 @@ 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
 
+**Option 3: Citrus Backend (pure Ruby, portable)**
+
+```ruby
+# Gemfile
+gem "tree_haver"
+gem "citrus"  # Pure Ruby parser, zero native dependencies
+
+# Code - Force Citrus backend for maximum portability
+TreeHaver.backend = :citrus
+
+# Check if Citrus backend is available
+if TreeHaver::Backends::Citrus.available?
+  puts "Citrus backend is ready!"
+  puts TreeHaver.capabilities
+  # => { backend: :citrus, parse: true, query: false, bytes_field: false }
+end
+```
+
+**⚠️ Citrus Backend Limitations:**
+
+- Uses Citrus grammars (not tree-sitter grammars)
+- No incremental parsing support
+- No query API
+- Pure Ruby performance (slower than native backends)
+- Best for: prototyping, environments without native extension support, teaching
+
 #### TruffleRuby
 
-TruffleRuby can use either the MRI or FFI backend:
+TruffleRuby can use the MRI, FFI, or Citrus backend:
 
 ```ruby
-# Use FFI backend (recommended)
+# Use FFI backend (recommended for tree-sitter grammars)
 TreeHaver.backend = :ffi
 
 # Or try MRI backend if ruby_tree_sitter compiles on your TruffleRuby version
 TreeHaver.backend = :mri
+
+# Or use Citrus backend for zero native dependencies
+TreeHaver.backend = :citrus
 ```
 
-### Advanced: Testing with Multiple Backends
+### Advanced: Thread-Safe Backend Switching
+
+TreeHaver provides `with_backend` for thread-safe, temporary backend switching. This is
+essential for testing, benchmarking, and applications that need different backends in
+different contexts.
 
-If you're developing a library that uses TreeHaver, you can test against different backends:
+#### Testing with Multiple Backends
+
+Test the same code path with different backends using `with_backend`:
 
 ```ruby
 # In your test setup
 RSpec.describe("MyParser") do
-  before do
-    TreeHaver.reset_backend!(to: :ffi)
+  # Test with each available backend
+  [:mri, :rust, :citrus].each do |backend_name|
+    context "with #{backend_name} backend" do
+      it "parses correctly" do
+        TreeHaver.with_backend(backend_name) do
+          parser = TreeHaver::Parser.new
+          result = parser.parse("x = 42")
+          expect(result.root_node.type).to eq("document")
+        end
+        # Backend automatically restored after block
+      end
+    end
+  end
+end
+```
+
+#### Thread Isolation
+
+Each thread can use a different backend safely—`with_backend` uses thread-local storage:
+
+```ruby
+threads = []
+
+threads << Thread.new do
+  TreeHaver.with_backend(:mri) do
+    # This thread uses MRI backend
+    parser = TreeHaver::Parser.new
+    100.times { parser.parse("x = 1") }
+  end
+end
+
+threads << Thread.new do
+  TreeHaver.with_backend(:citrus) do
+    # This thread uses Citrus backend simultaneously
+    parser = TreeHaver::Parser.new
+    100.times { parser.parse("x = 1") }
   end
+end
+
+threads.each(&:join)
+```
+
+#### Nested Blocks
 
-  after do
-    TreeHaver.reset_backend!(to: :auto)
+`with_backend` supports nesting—inner blocks override outer blocks:
+
+```ruby
+TreeHaver.with_backend(:rust) do
+  puts TreeHaver.effective_backend  # => :rust
+
+  TreeHaver.with_backend(:citrus) do
+    puts TreeHaver.effective_backend  # => :citrus
   end
 
-  it "parses correctly with FFI backend" do
-    # Your test code
+  puts TreeHaver.effective_backend  # => :rust (restored)
+end
+```
+
+#### Fallback Pattern
+
+Try one backend, fall back to another on failure:
+
+```ruby
+def parse_with_fallback(source)
+  TreeHaver.with_backend(:mri) do
+    TreeHaver::Parser.new.tap { |p| p.language = load_language }.parse(source)
+  end
+rescue TreeHaver::NotAvailable
+  # Fall back to Citrus if MRI backend unavailable
+  TreeHaver.with_backend(:citrus) do
+    TreeHaver::Parser.new.tap { |p| p.language = load_language }.parse(source)
   end
 end
 ```
@@ -912,7 +1294,7 @@ You can support the development of kettle-rb tools via
 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
@@ -922,7 +1304,9 @@ 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
@@ -932,14 +1316,16 @@ 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
 
 ### 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).
+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`.
 
@@ -1010,7 +1396,7 @@ 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]
+> —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.
@@ -1027,7 +1413,7 @@ spec.add_dependency("tree_haver", "~> 1.0")
 <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.
+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:
@@ -1114,7 +1500,6 @@ Thanks for RTFM. ☺️
 [✉️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
@@ -1238,7 +1623,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-0.501-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.067-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