tree_haver 3.2.6 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e544c31dc86e71be78cfcf24e7cbf8a779ef954845b736ec37ed6b550ffe714
-  data.tar.gz: 54f83ef36c8167f5071db278ce33f2603864d339a9c246a733957da41540eab4
+  metadata.gz: 6a3704393a089cd839f41b5bd1b84c159bfef219ea41ba993c73266c00183004
+  data.tar.gz: 149a7ff9f6812c0173b17e6a0646d802843da9bce67e6c29054b422e98bb867e
 SHA512:
-  metadata.gz: c991da086ba12a279f461f337e7dfa9d0b98d8d6d4f4c5d3d78cc3b848a6174ed42ce71b674e8a2d4ed81c5b17289d6c3903c2ef813db86cd4557a33aa1c1599
-  data.tar.gz: 034b9f7df24e5f757013f011b7661559fed243b3fde752d95ab2cac94a0fdfc8270d9ca002d07972c74c1d5455293ac12c7472eacdc106934051cc3231d005b9
+  metadata.gz: 03dc62871eac66744c11ca4adbcad33913d52bb9e1134175bdae549faf339ff6206fb4e98087441ffe74a3cba8f2f49684649f8591442e8a38ed74ce8ada50f8
+  data.tar.gz: ef5413e0bb4e2b147fe9e97d560a71994b4324f9e26837752783b27d59fa935da5890c9b1b1a193f2867164f349d522a42e5ec009fabff3b07786d35fdddd928

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-**# Changelog
+# Changelog
 
 [![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog]
 
@@ -30,6 +30,42 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [4.0.0] - 2026-01-08
+
+- TAG: [v4.0.0][4.0.0t]
+- COVERAGE: 95.31% -- 2031/2131 lines in 28 files
+- BRANCH COVERAGE: 84.21% -- 805/956 branches in 28 files
+- 95.48% documented
+
+### Added
+
+- **BackendRegistry**: New `TreeHaver::BackendRegistry` module for registering backend availability checkers
+  - Allows external gems (like `commonmarker-merge`, `markly-merge`, `rbs-merge`) to register their availability checkers
+  - `register_availability_checker(backend_name, &block)` - Register a callable that returns true if backend is available
+  - `available?(backend_name)` - Check if a backend is available (results are cached)
+  - `registered?(backend_name)` - Check if a checker is registered
+  - `registered_backends` - Get all registered backend names
+  - Used by `TreeHaver::RSpec::DependencyTags` for dynamic backend detection
+- **Plugin System**: `commonmarker-merge` and `markly-merge` now provide their own backends via `TreeHaver`'s registry system, removing them from `TreeHaver` core.
+- **Backend Architecture Documentation**: Added comprehensive documentation to base classes and all tree-sitter backends explaining the two backend categories:
+  - Tree-sitter backends (MRI, Rust, FFI, Java): Use `TreeHaver::Tree` and `TreeHaver::Node` wrappers for raw tree-sitter objects
+  - Pure-Ruby/Plugin backends (Citrus, Prism, Psych, Commonmarker, Markly): Define own `Backend::X::Tree` and `Backend::X::Node` classes
+
+### Changed
+
+- **Base Class Inheritance**: `TreeHaver::Tree` and `TreeHaver::Node` now properly inherit from their respective `Base::` classes
+  - `TreeHaver::Tree < Base::Tree` - inherits `inner_tree`, `source`, `lines` attributes and default implementations
+  - `TreeHaver::Node < Base::Node` - inherits `inner_node`, `source`, `lines` attributes and API contract
+  - Base classes document the API contract; subclasses document divergence
+- **Base::Node#initialize**: Now accepts keyword arguments `source:` and `lines:` instead of positional for consistency with subclasses
+- **DependencyTags**: Now uses `BackendRegistry.available?(:backend_name)` instead of hardcoded `TreeHaver::Backends::*` checks
+- **TreeHaver**: `commonmarker` and `markly` backends are no longer built-in. Use `commonmarker-merge` and `markly-merge` gems which register themselves.
+- **All backends**: Now register their availability checkers with `BackendRegistry` when loaded (MRI, Rust, FFI, Java, Prism, Psych, Citrus)
+
+### Removed
+
+- **TreeHaver**: Removed `TreeHaver::Backends::Commonmarker` and `TreeHaver::Backends::Markly` modules. These implementations have moved to their respective gems.
+
 ## [3.2.6] - 2026-01-06
 
 - TAG: [v3.2.6][3.2.6t]
@@ -915,7 +951,9 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.6...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/kettle-rb/tree_haver/compare/v3.2.6...v4.0.0
+[4.0.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v4.0.0
 [3.2.6]: https://github.com/kettle-rb/tree_haver/compare/v3.2.5...v3.2.6
 [3.2.6t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.6
 [3.2.5]: https://github.com/kettle-rb/tree_haver/compare/v3.2.4...v3.2.5
@@ -941,4 +979,4 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 [2.0.0]: https://github.com/kettle-rb/tree_haver/compare/v1.0.0...v2.0.0
 [2.0.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v2.0.0
 [1.0.0]: https://github.com/kettle-rb/tree_haver/compare/a89211bff10f4440b96758a8ac9d7d539001b0c8...v1.0.0
-[1.0.0t]: https://github.com/kettle-rb/tree_haver/tags/v1.0.0**
+[1.0.0t]: https://github.com/kettle-rb/tree_haver/tags/v1.0.0

data/README.md

@@ -341,12 +341,36 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 | [rbs-merge][rbs-merge]                   | RBS                  | [tree-sitter-bash][ts-rbs] (via tree_haver), [RBS][rbs] (`rbs` std lib gem)                         | Smart merge for Ruby type signatures                                             |
 | [toml-merge][toml-merge]                 | TOML                 | [Citrus + toml-rb][toml-rb] (default, via tree_haver), [tree-sitter-toml][ts-toml] (via tree_haver) | Smart merge for TOML files                                                       |
 
+#### Backend Platform Compatibility
+
+tree_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:
+
+| Platform 👉️<br> TreeHaver Backend 👇️         | MRI | JRuby | TruffleRuby | Notes                                               |
+|------------------------------------------------|:---:|:-----:|:-----------:|-----------------------------------------------------|
+| **MRI** ([ruby_tree_sitter][ruby_tree_sitter]) |  ✅  |   ❌   |      ❌      | C extension, MRI only                               |
+| **Rust** ([tree_stump][tree_stump])            |  ✅  |   ❌   |      ❌      | Rust extension via magnus/rb-sys, MRI only          |
+| **FFI**                                        |  ✅  |   ✅   |      ❌      | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE` |
+| **Java** ([jtreesitter][jtreesitter])          |  ❌  |   ✅   |      ❌      | JRuby only, requires grammar JARs                   |
+| **Prism**                                      |  ✅  |   ✅   |      ✅      | Ruby parsing, stdlib in Ruby 3.4+                   |
+| **Psych**                                      |  ✅  |   ✅   |      ✅      | YAML parsing, stdlib                                |
+| **Citrus**                                     |  ✅  |   ✅   |      ✅      | Pure Ruby, no native dependencies                   |
+| **Commonmarker**                               |  ✅  |   ❌   |      ❓      | Rust extension for Markdown                         |
+| **Markly**                                     |  ✅  |   ❌   |      ❓      | C extension for Markdown                            |
+
+**Legend**: ✅ = Works, ❌ = Does not work, ❓ = Untested
+
+**Why some backends don't work on certain platforms**:
+
+- **JRuby**: Runs on the JVM; cannot load native C/Rust extensions (`.so` files)
+- **TruffleRuby**: Has C API emulation via Sulong/LLVM, but it doesn't expose all MRI internals that native extensions require (e.g., `RBasic.flags`, `rb_gc_writebarrier`)
+- **FFI on TruffleRuby**: TruffleRuby's FFI implementation doesn't support returning structs by value, which tree-sitter's C API requires
+
 **Example implementations** for the gem templating use case:
 
-| Gem | Purpose | Description |
-| --- | --- | --- |
-| [kettle-dev](https://github.com/kettle-rb/kettle-dev) | Gem Development | Gem templating tool using `*-merge` gems |
-| [kettle-jem](https://github.com/kettle-rb/kettle-jem) | Gem Templating | Gem template library with smart merge support |
+| Gem                      | Purpose         | Description                                   |
+|--------------------------|-----------------|-----------------------------------------------|
+| [kettle-dev][kettle-dev] | Gem Development | Gem templating tool using `*-merge` gems      |
+| [kettle-jem][kettle-jem] | Gem Templating  | Gem template library with smart merge support |
 
 [tree_haver]: https://github.com/kettle-rb/tree_haver
 [ast-merge]: https://github.com/kettle-rb/ast-merge
@@ -366,16 +390,18 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 [prism]: https://github.com/ruby/prism
 [psych]: https://github.com/ruby/psych
 [ts-json]: https://github.com/tree-sitter/tree-sitter-json
+[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
 [ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
+[ts-rbs]: https://github.com/joker1007/tree-sitter-rbs
 [ts-toml]: https://github.com/tree-sitter-grammars/tree-sitter-toml
+[dotenv]: https://github.com/bkeepers/dotenv
 [rbs]: https://github.com/ruby/rbs
 [toml-rb]: https://github.com/emancu/toml-rb
 [markly]: https://github.com/ioquatix/markly
 [commonmarker]: https://github.com/gjtorikian/commonmarker
-
-
-[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
-[dotenv]: https://github.com/bkeepers/dotenv
+[ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
+[tree_stump]: https://github.com/joker1007/tree_stump
+[jtreesitter]: https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter
 
 ### Comparison with Other Ruby AST / Parser Bindings
 
@@ -796,6 +822,65 @@ You can also set the backend via environment variable:
 export TREE_HAVER_BACKEND=rust
 ```
 
+### Backend Registry
+
+TreeHaver provides a `BackendRegistry` module that allows external gems to register their backend availability checkers. This enables dynamic backend detection without hardcoding dependencies.
+
+#### Registering a Backend Availability Checker
+
+External gems (like `commonmarker-merge`, `markly-merge`, `rbs-merge`) can register their availability checker when loaded:
+
+```ruby
+# In your gem's backend module
+TreeHaver::BackendRegistry.register_availability_checker(:my_backend) do
+  # Return true if backend is available
+  require "my_backend_gem"
+  true
+rescue LoadError
+  false
+end
+```
+
+#### Checking Backend Availability
+
+```ruby
+# Check if a backend is available
+TreeHaver::BackendRegistry.available?(:commonmarker)  # => true/false
+TreeHaver::BackendRegistry.available?(:markly)        # => true/false
+TreeHaver::BackendRegistry.available?(:rbs)           # => true/false
+
+# Check if a checker is registered
+TreeHaver::BackendRegistry.registered?(:my_backend)   # => true/false
+
+# Get all registered backend names
+TreeHaver::BackendRegistry.registered_backends        # => [:mri, :rust, :ffi, ...]
+```
+
+#### How It Works
+
+1. Built-in backends (MRI, Rust, FFI, Java, Prism, Psych, Citrus) automatically register their checkers when loaded
+2. External gems register their checkers when their backend module is loaded
+3. `TreeHaver::RSpec::DependencyTags` uses the registry to dynamically detect available backends
+4. Results are cached for performance (use `clear_cache!` to reset)
+
+#### RSpec Integration
+
+The `BackendRegistry` is used by `TreeHaver::RSpec::DependencyTags` to configure RSpec exclusion filters:
+
+```ruby
+# In your spec_helper.rb
+require "tree_haver/rspec/dependency_tags"
+
+# Then in specs, use tags to skip tests when backends aren't available
+it "requires commonmarker", :commonmarker_backend do
+  # This test only runs when commonmarker is available
+end
+
+it "requires markly", :markly_backend do
+  # This test only runs when markly is available
+end
+```
+
 ### Environment Variables
 
 TreeHaver recognizes several environment variables for configuration:
@@ -2097,7 +2182,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-2.422-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.131-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
@@ -2117,6 +2202,3 @@ Thanks for RTFM. ☺️
 [💎appraisal2]: https://github.com/appraisal-rb/appraisal2
 [💎appraisal2-img]: https://img.shields.io/badge/appraised_by-appraisal2-34495e.svg?plastic&logo=ruby&logoColor=white
 [💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/
-
-[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
-[dotenv]: https://github.com/bkeepers/dotenv

data/lib/tree_haver/backend_registry.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Registry for backend dependency tag availability checkers
+  #
+  # This module allows external gems (like commonmarker-merge, markly-merge, rbs-merge)
+  # to register their availability checker for RSpec dependency tags without
+  # TreeHaver needing to know about them directly.
+  #
+  # == Purpose
+  #
+  # When running RSpec tests with dependency tags (e.g., `:commonmarker_backend`),
+  # TreeHaver needs to know if each backend is available. Rather than hardcoding
+  # checks like `TreeHaver::Backends::Commonmarker.available?` (which would fail
+  # if the backend module doesn't exist), the BackendRegistry provides a dynamic
+  # way for backends to register their availability checkers.
+  #
+  # == Built-in vs External Backends
+  #
+  # - **Built-in backends** (MRI, Rust, FFI, Java, Prism, Psych, Citrus) register
+  #   their checkers automatically when loaded from `tree_haver/backends/*.rb`
+  # - **External backends** (commonmarker-merge, markly-merge, rbs-merge) register
+  #   their checkers when their backend module is loaded
+  #
+  # == Thread Safety
+  #
+  # All operations are thread-safe using a Mutex for synchronization.
+  # Results are cached after first check for performance.
+  #
+  # @example Registering a backend availability checker (in your gem)
+  #   # In commonmarker-merge/lib/commonmarker/merge/backend.rb
+  #   TreeHaver::BackendRegistry.register_availability_checker(:commonmarker) do
+  #     available?
+  #   end
+  #
+  # @example Checking backend availability
+  #   TreeHaver::BackendRegistry.available?(:commonmarker)  # => true/false
+  #   TreeHaver::BackendRegistry.available?(:markly)        # => true/false
+  #   TreeHaver::BackendRegistry.available?(:rbs)           # => true/false
+  #
+  # @example Checking if a checker is registered
+  #   TreeHaver::BackendRegistry.registered?(:commonmarker) # => true/false
+  #
+  # @example Getting all registered backends
+  #   TreeHaver::BackendRegistry.registered_backends # => [:mri, :rust, :ffi, ...]
+  #
+  # @see TreeHaver::RSpec::DependencyTags Uses BackendRegistry for dynamic backend detection
+  # @api public
+  module BackendRegistry
+    @mutex = Mutex.new
+    @availability_checkers = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+    @availability_cache = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+
+    module_function
+
+    # Register an availability checker for a backend
+    #
+    # The checker should be a callable (lambda/proc/block) that returns true if
+    # the backend is available and can be used. The checker is called lazily
+    # (only when {available?} is first called for this backend).
+    #
+    # @param backend_name [Symbol, String] the backend name (e.g., :commonmarker, :markly)
+    # @param checker [#call, nil] a callable that returns true if the backend is available
+    # @yield Block form of checker (alternative to passing a callable)
+    # @yieldreturn [Boolean] true if the backend is available
+    # @return [void]
+    # @raise [ArgumentError] if no checker callable or block is provided
+    # @raise [ArgumentError] if checker doesn't respond to #call
+    #
+    # @example Register with a block
+    #   TreeHaver::BackendRegistry.register_availability_checker(:commonmarker) do
+    #     require "commonmarker"
+    #     true
+    #   rescue LoadError
+    #     false
+    #   end
+    #
+    # @example Register with a lambda
+    #   checker = -> { Commonmarker::Merge::Backend.available? }
+    #   TreeHaver::BackendRegistry.register_availability_checker(:commonmarker, checker)
+    #
+    # @example Register referencing the module's available? method
+    #   TreeHaver::BackendRegistry.register_availability_checker(:my_backend) do
+    #     available?  # Calls the enclosing module's available? method
+    #   end
+    def register_availability_checker(backend_name, checker = nil, &block)
+      callable = checker || block
+      raise ArgumentError, "Must provide a checker callable or block" unless callable
+      raise ArgumentError, "Checker must respond to #call" unless callable.respond_to?(:call)
+
+      @mutex.synchronize do
+        @availability_checkers[backend_name.to_sym] = callable
+        # Clear cache for this backend when re-registering
+        @availability_cache.delete(backend_name.to_sym)
+      end
+      nil
+    end
+
+    # Check if a backend is available
+    #
+    # If a checker was registered via {register_availability_checker}, it is called
+    # (and the result cached). If no checker is registered, falls back to checking
+    # `TreeHaver::Backends::<Name>.available?` for built-in backends.
+    #
+    # Results are cached to avoid repeated expensive checks (e.g., requiring gems).
+    # Use {clear_cache!} to reset the cache if backend availability may have changed.
+    #
+    # @param backend_name [Symbol, String] the backend name to check
+    # @return [Boolean] true if the backend is available, false otherwise
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.available?(:commonmarker)  # => true
+    #   TreeHaver::BackendRegistry.available?(:nonexistent)   # => false
+    def available?(backend_name)
+      key = backend_name.to_sym
+
+      # First, check cache and get checker without holding mutex for long
+      checker = nil
+      @mutex.synchronize do
+        # Return cached result if available
+        return @availability_cache[key] if @availability_cache.key?(key)
+
+        # Get registered checker (if any)
+        checker = @availability_checkers[key]
+      end
+
+      # Compute result OUTSIDE the mutex to avoid deadlock when loading backends
+      # (loading a backend module triggers register_availability_checker which needs the mutex)
+      result = if checker
+        # Use the registered checker
+        begin
+          checker.call
+        rescue StandardError
+          false
+        end
+      else
+        # Fall back to checking TreeHaver::Backends::<Name>
+        # This may load the backend module, which will register its checker
+        check_builtin_backend(key)
+      end
+
+      # Cache the result
+      @mutex.synchronize do
+        # Double-check cache in case another thread computed it
+        return @availability_cache[key] if @availability_cache.key?(key)
+        @availability_cache[key] = result
+      end
+
+      result
+    end
+
+    # Check if an availability checker is registered for a backend
+    #
+    # @param backend_name [Symbol, String] the backend name
+    # @return [Boolean] true if a checker is registered
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.registered?(:commonmarker)  # => true (if loaded)
+    #   TreeHaver::BackendRegistry.registered?(:nonexistent)   # => false
+    def registered?(backend_name)
+      @mutex.synchronize do
+        @availability_checkers.key?(backend_name.to_sym)
+      end
+    end
+
+    # Get all registered backend names
+    #
+    # @return [Array<Symbol>] list of registered backend names
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.registered_backends
+    #   # => [:mri, :rust, :ffi, :java, :prism, :psych, :citrus, :commonmarker, :markly]
+    def registered_backends
+      @mutex.synchronize do
+        @availability_checkers.keys.dup
+      end
+    end
+
+    # Clear the availability cache
+    #
+    # Useful for testing or when backend availability may have changed
+    # (e.g., after installing a gem mid-process).
+    #
+    # @return [void]
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.clear_cache!
+    #   # Next call to available? will re-check
+    def clear_cache!
+      @mutex.synchronize do
+        @availability_cache.clear
+      end
+      nil
+    end
+
+    # Clear all registrations and cache
+    #
+    # Removes all registered checkers and cached results.
+    # Primarily useful for testing to reset state between test cases.
+    #
+    # @return [void]
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.clear!
+    def clear!
+      @mutex.synchronize do
+        @availability_checkers.clear
+        @availability_cache.clear
+      end
+      nil
+    end
+
+    # Check a built-in TreeHaver backend
+    #
+    # Attempts to find the backend module at `TreeHaver::Backends::<Name>` and
+    # call its `available?` method. This is the fallback when no explicit
+    # checker has been registered.
+    #
+    # @param backend_name [Symbol] the backend name (e.g., :mri, :rust, :ffi)
+    # @return [Boolean] true if the backend module exists and reports available
+    # @api private
+    def check_builtin_backend(backend_name)
+      # Convert backend_name to PascalCase constant name
+      # e.g., :mri -> "MRI", :ffi -> "FFI", :commonmarker -> "Commonmarker"
+      const_name = backend_name.to_s.split("_").map(&:capitalize).join
+      backend_mod = TreeHaver::Backends.const_get(const_name)
+      backend_mod.respond_to?(:available?) && backend_mod.available?
+    rescue NameError
+      # Backend module doesn't exist
+      false
+    end
+    private_class_method :check_builtin_backend
+  end
+end

data/lib/tree_haver/backends/citrus.rb

@@ -42,10 +42,11 @@ module TreeHaver
           @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           begin
             require "citrus"
-
             @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           rescue LoadError
             @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          rescue StandardError
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
           end
           @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
@@ -492,6 +493,11 @@ module TreeHaver
           {row: lines_before, column: column}
         end
       end
+
+      # Register availability checker for RSpec dependency tags
+      TreeHaver::BackendRegistry.register_availability_checker(:citrus) do
+        available?
+      end
     end
   end
 end

data/lib/tree_haver/backends/ffi.rb

@@ -15,6 +15,23 @@ module TreeHaver
     # Not yet supported:
     # - Query API (tree-sitter queries/patterns)
     #
+    # == Tree/Node Architecture
+    #
+    # This backend (like all tree-sitter backends: MRI, Rust, FFI, Java) does NOT
+    # define its own Tree or Node classes. Instead:
+    #
+    # - Parser#parse returns raw FFI-wrapped tree objects
+    # - These are wrapped by `TreeHaver::Tree` (inherits from `Base::Tree`)
+    # - `TreeHaver::Tree#root_node` wraps raw nodes in `TreeHaver::Node`
+    #
+    # This differs from pure-Ruby backends (Citrus, Prism, Psych) which define
+    # their own `Backend::X::Tree` and `Backend::X::Node` classes.
+    #
+    # @see TreeHaver::Tree The wrapper class for tree-sitter Tree objects
+    # @see TreeHaver::Node The wrapper class for tree-sitter Node objects
+    # @see TreeHaver::Base::Tree Base class documenting the Tree API contract
+    # @see TreeHaver::Base::Node Base class documenting the Node API contract
+    #
     # == Platform Compatibility
     #
     # - MRI Ruby: ✓ Full support
@@ -56,19 +73,24 @@ module TreeHaver
         # @note Returns false on TruffleRuby because TruffleRuby's FFI doesn't support
         #   STRUCT_BY_VALUE return types (used by ts_tree_root_node, ts_node_child, etc.)
         def ffi_gem_available?
-          return @loaded if @load_attempted
+          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
 
-          @load_attempted = true
-          @loaded = begin
+          @loaded = begin # rubocop:disable ThreadSafety/ClassInstanceVariable
             # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
             # which tree-sitter uses extensively (ts_tree_root_node, ts_node_child, etc.)
-            return false if RUBY_ENGINE == "truffleruby"
-
-            require "ffi"
-            true
+            if RUBY_ENGINE == "truffleruby"
+              false
+            else
+              require "ffi"
+              true
+            end
           rescue LoadError
             false
+          rescue StandardError
+            false
           end
+          @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
 
         # Reset the load state (primarily for testing)
@@ -76,8 +98,8 @@ module TreeHaver
         # @return [void]
         # @api private
         def reset!
-          @load_attempted = false
-          @loaded = false
+          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
 
         # Get capabilities supported by this backend
@@ -717,6 +739,11 @@ module TreeHaver
           type <=> other.type
         end
       end
+
+      # Register availability checker for RSpec dependency tags
+      TreeHaver::BackendRegistry.register_availability_checker(:ffi) do
+        available?
+      end
     end
   end
 end