tree_haver 1.0.0 → 3.0.0

data/lib/tree_haver.rb

@@ -3,13 +3,16 @@
 # External gems
 require "version_gem"
 
+# Standard library
+require "set"
+
 # This gem
 require_relative "tree_haver/version"
 require_relative "tree_haver/language_registry"
 
-# TreeHaver is a cross-Ruby adapter for the Tree-sitter parsing library.
+# TreeHaver is a cross-Ruby adapter for the tree-sitter parsing library.
 #
-# It provides a unified API for parsing source code using Tree-sitter grammars,
+# It provides a unified API for parsing source code using tree-sitter grammars,
 # working seamlessly across MRI Ruby, JRuby, and TruffleRuby.
 #
 # @example Basic usage with TOML
@@ -54,15 +57,18 @@ require_relative "tree_haver/language_registry"
 #   TreeHaver.backend = :mri  # Force MRI backend
 #   TreeHaver.backend = :auto # Auto-select (default)
 #
-# @see https://tree-sitter.github.io/tree-sitter/ Tree-sitter documentation
+# @see https://tree-sitter.github.io/tree-sitter/ tree-sitter documentation
 # @see GrammarFinder For automatic grammar library discovery
 module TreeHaver
   # Base error class for TreeHaver exceptions
+  # @see https://github.com/Faveod/ruby-tree-sitter/pull/83 for inherit from Exception reasoning
   #
   # @abstract Subclass to create specific error types
-  class Error < StandardError; end
+  class Error < Exception; end  # rubocop:disable Lint/InheritException
 
   # Raised when a requested backend or feature is not available
+  # These are serious errors that extends Exception (not StandardError).
+  # @see https://github.com/Faveod/ruby-tree-sitter/pull/83 for inherit from Exception reasoning
   #
   # This can occur when:
   # - Required native libraries are not installed
@@ -77,18 +83,59 @@ module TreeHaver
   #   end
   class NotAvailable < Error; end
 
+  # Raised when attempting to use backends that are known to conflict
+  #
+  # This is a serious error that extends Exception (not StandardError) because
+  # it prevents a segmentation fault. The MRI backend (ruby_tree_sitter) and
+  # FFI backend cannot coexist in the same process - once MRI loads, FFI will
+  # segfault when trying to set a language on a parser.
+  #
+  # This protection can be disabled with `TreeHaver.backend_protect = false`
+  # but doing so risks segfaults.
+  #
+  # @example Handling backend conflicts
+  #   begin
+  #     # This will raise if MRI was already used
+  #     TreeHaver.with_backend(:ffi) { parser.language = lang }
+  #   rescue TreeHaver::BackendConflict => e
+  #     puts "Backend conflict: #{e.message}"
+  #     # Fall back to a compatible backend
+  #   end
+  #
+  # @example Disabling protection (not recommended)
+  #   TreeHaver.backend_protect = false
+  #   # Now you can test backend conflicts (at risk of segfaults)
+  class BackendConflict < Error; end
+
   # Namespace for backend implementations
   #
   # TreeHaver provides multiple backends to support different Ruby implementations:
   # - {Backends::MRI} - Uses ruby_tree_sitter (MRI C extension)
   # - {Backends::Rust} - Uses tree_stump (Rust extension with precompiled binaries)
   # - {Backends::FFI} - Uses Ruby FFI to call libtree-sitter directly
-  # - {Backends::Java} - Uses JRuby's Java integration (planned)
+  # - {Backends::Java} - Uses JRuby's Java integration
+  # - {Backends::Citrus} - Uses Citrus PEG parser (pure Ruby, portable)
   module Backends
     autoload :MRI, File.join(__dir__, "tree_haver", "backends", "mri")
     autoload :Rust, File.join(__dir__, "tree_haver", "backends", "rust")
     autoload :FFI, File.join(__dir__, "tree_haver", "backends", "ffi")
     autoload :Java, File.join(__dir__, "tree_haver", "backends", "java")
+    autoload :Citrus, File.join(__dir__, "tree_haver", "backends", "citrus")
+
+    # Known backend conflicts
+    #
+    # Maps each backend to an array of backends that block it from working.
+    # For example, :ffi is blocked by :mri because once ruby_tree_sitter loads,
+    # FFI calls to ts_parser_set_language will segfault.
+    #
+    # @return [Hash{Symbol => Array<Symbol>}]
+    BLOCKED_BY = {
+      mri: [],
+      rust: [],
+      ffi: [:mri],  # FFI segfaults if MRI (ruby_tree_sitter) has been loaded
+      java: [],
+      citrus: [],
+    }.freeze
   end
 
   # Security utilities for validating paths before loading shared libraries
@@ -119,11 +166,98 @@ module TreeHaver
   # @see PathValidator
   autoload :GrammarFinder, File.join(__dir__, "tree_haver", "grammar_finder")
 
+  # Citrus grammar finder for discovering and registering Citrus-based parsers
+  #
+  # @example Register toml-rb
+  #   finder = TreeHaver::CitrusGrammarFinder.new(
+  #     language: :toml,
+  #     gem_name: "toml-rb",
+  #     grammar_const: "TomlRB::Document"
+  #   )
+  #   finder.register! if finder.available?
+  #
+  # @see CitrusGrammarFinder
+  autoload :CitrusGrammarFinder, File.join(__dir__, "tree_haver", "citrus_grammar_finder")
+
+  # Unified Node wrapper providing consistent API across backends
+  autoload :Node, File.join(__dir__, "tree_haver", "node")
+
+  # Unified Tree wrapper providing consistent API across backends
+  autoload :Tree, File.join(__dir__, "tree_haver", "tree")
+
   # Get the current backend selection
   #
-  # @return [Symbol] one of :auto, :mri, :ffi, or :java
+  # @return [Symbol] one of :auto, :mri, :rust, :ffi, :java, or :citrus
   # @note Can be set via ENV["TREE_HAVER_BACKEND"]
   class << self
+    # Whether backend conflict protection is enabled
+    #
+    # When true (default), TreeHaver will raise BackendConflict if you try to
+    # use a backend that is known to conflict with a previously used backend.
+    # For example, FFI will not work after MRI has been used.
+    #
+    # Set to false to disable protection (useful for testing compatibility).
+    #
+    # @return [Boolean]
+    # @example Disable protection for testing
+    #   TreeHaver.backend_protect = false
+    attr_writer :backend_protect
+
+    # Check if backend conflict protection is enabled
+    #
+    # @return [Boolean] true if protection is enabled (default)
+    def backend_protect?
+      return @backend_protect if defined?(@backend_protect) # rubocop:disable ThreadSafety/ClassInstanceVariable
+      true  # Default is protected
+    end
+
+    # Alias for backend_protect?
+    def backend_protect
+      backend_protect?
+    end
+
+    # Track which backends have been used in this process
+    #
+    # @return [Set<Symbol>] set of backend symbols that have been used
+    def backends_used
+      @backends_used ||= Set.new # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Record that a backend has been used
+    #
+    # @param backend [Symbol] the backend that was used
+    # @return [void]
+    # @api private
+    def record_backend_usage(backend)
+      backends_used << backend
+    end
+
+    # Check if a backend would conflict with previously used backends
+    #
+    # @param backend [Symbol] the backend to check
+    # @return [Array<Symbol>] list of previously used backends that block this one
+    def conflicting_backends_for(backend)
+      blockers = Backends::BLOCKED_BY[backend] || []
+      blockers & backends_used.to_a
+    end
+
+    # Check if using a backend would cause a conflict
+    #
+    # @param backend [Symbol] the backend to check
+    # @raise [BackendConflict] if protection is enabled and there's a conflict
+    # @return [void]
+    def check_backend_conflict!(backend)
+      return unless backend_protect?
+
+      conflicts = conflicting_backends_for(backend)
+      return if conflicts.empty?
+
+      raise BackendConflict,
+        "Cannot use #{backend} backend: it is blocked by previously used backend(s): #{conflicts.join(", ")}. " \
+          "The #{backend} backend will segfault when #{conflicts.first} has already loaded. " \
+          "To disable this protection (at risk of segfaults), set TreeHaver.backend_protect = false"
+    end
+
     # @example
     #   TreeHaver.backend  # => :auto
     def backend
@@ -132,13 +266,14 @@ module TreeHaver
       when "rust" then :rust
       when "ffi" then :ffi
       when "java" then :java
+      when "citrus" then :citrus
       else :auto
       end
     end
 
     # Set the backend to use
     #
-    # @param name [Symbol, String, nil] backend name (:auto, :mri, :rust, :ffi, :java)
+    # @param name [Symbol, String, nil] backend name (:auto, :mri, :rust, :ffi, :java, :citrus)
     # @return [Symbol, nil] the backend that was set
     # @example Force FFI backend
     #   TreeHaver.backend = :ffi
@@ -162,20 +297,218 @@ module TreeHaver
       @backend = to&.to_sym # rubocop:disable ThreadSafety/ClassInstanceVariable
     end
 
+    # Thread-local backend context storage
+    #
+    # Returns a hash containing the thread-local backend context with keys:
+    # - :backend - The backend name (Symbol) or nil if using global default
+    # - :depth - The nesting depth (Integer) for proper cleanup
+    #
+    # @return [Hash{Symbol => Object}] context hash with :backend and :depth keys
+    # @example
+    #   ctx = TreeHaver.current_backend_context
+    #   ctx[:backend]  # => nil or :ffi, :mri, etc.
+    #   ctx[:depth]    # => 0, 1, 2, etc.
+    def current_backend_context
+      Thread.current[:tree_haver_backend_context] ||= {
+        backend: nil,  # nil means "use global default"
+        depth: 0,       # Track nesting depth for proper cleanup
+      }
+    end
+
+    # Get the effective backend for current context
+    #
+    # Priority: thread-local context → global @backend → :auto
+    #
+    # @return [Symbol] the backend to use
+    # @example
+    #   TreeHaver.effective_backend  # => :auto (default)
+    # @example With thread-local context
+    #   TreeHaver.with_backend(:ffi) do
+    #     TreeHaver.effective_backend  # => :ffi
+    #   end
+    def effective_backend
+      ctx = current_backend_context
+      ctx[:backend] || backend || :auto
+    end
+
+    # Execute a block with a specific backend in thread-local context
+    #
+    # This method provides temporary, thread-safe backend switching for a block of code.
+    # The backend setting is automatically restored when the block exits, even if
+    # an exception is raised. Supports nesting—inner blocks override outer blocks,
+    # and each level is properly unwound.
+    #
+    # Thread Safety: Each thread maintains its own backend context, so concurrent
+    # threads can safely use different backends without interfering with each other.
+    #
+    # Use Cases:
+    # - Testing: Test the same code path with different backends
+    # - Performance comparison: Benchmark parsing with different backends
+    # - Fallback scenarios: Try one backend, fall back to another on failure
+    # - Thread isolation: Different threads can use different backends safely
+    #
+    # @param name [Symbol, String] backend name (:mri, :rust, :ffi, :java, :citrus, :auto)
+    # @yield block to execute with the specified backend
+    # @return [Object] the return value of the block
+    # @raise [ArgumentError] if backend name is nil
+    # @raise [BackendConflict] if the requested backend conflicts with a previously used backend
+    #
+    # @example Basic usage
+    #   TreeHaver.with_backend(:mri) do
+    #     parser = TreeHaver::Parser.new
+    #     tree = parser.parse(source)
+    #   end
+    #   # Backend is automatically restored here
+    #
+    # @example Nested blocks (inner overrides outer)
+    #   TreeHaver.with_backend(:rust) do
+    #     parser1 = TreeHaver::Parser.new  # Uses :rust
+    #     TreeHaver.with_backend(:citrus) do
+    #       parser2 = TreeHaver::Parser.new  # Uses :citrus
+    #     end
+    #     parser3 = TreeHaver::Parser.new  # Back to :rust
+    #   end
+    #
+    # @example Testing 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
+    #
+    # @example Exception safety (backend restored even on error)
+    #   TreeHaver.with_backend(:mri) do
+    #     raise "Something went wrong"
+    #   rescue
+    #     # Handle error
+    #   end
+    #   # Backend is still restored to its previous value
+    #
+    # @example Thread isolation
+    #   threads = [:mri, :rust].map do |backend_name|
+    #     Thread.new do
+    #       TreeHaver.with_backend(backend_name) do
+    #         # Each thread uses its own backend independently
+    #         TreeHaver::Parser.new
+    #       end
+    #     end
+    #   end
+    #   threads.each(&:join)
+    #
+    # @see #effective_backend
+    # @see #current_backend_context
+    def with_backend(name)
+      raise ArgumentError, "Backend name required" if name.nil?
+
+      # Get context FIRST to ensure it exists
+      ctx = current_backend_context
+      old_backend = ctx[:backend]
+      old_depth = ctx[:depth]
+
+      begin
+        # Set new backend and increment depth
+        ctx[:backend] = name.to_sym
+        ctx[:depth] += 1
+
+        # Execute block
+        yield
+      ensure
+        # Restore previous backend and depth
+        # This ensures proper unwinding even with exceptions
+        ctx[:backend] = old_backend
+        ctx[:depth] = old_depth
+      end
+    end
+
+    # Resolve the effective backend considering explicit override
+    #
+    # Priority: explicit > thread context > global > :auto
+    #
+    # @param explicit_backend [Symbol, String, nil] explicitly requested backend
+    # @return [Symbol] the backend to use
+    # @example
+    #   TreeHaver.resolve_effective_backend(:ffi)  # => :ffi
+    # @example With thread-local context
+    #   TreeHaver.with_backend(:mri) do
+    #     TreeHaver.resolve_effective_backend(nil)  # => :mri
+    #     TreeHaver.resolve_effective_backend(:ffi)  # => :ffi (explicit wins)
+    #   end
+    def resolve_effective_backend(explicit_backend = nil)
+      return explicit_backend.to_sym if explicit_backend
+      effective_backend
+    end
+
+    # Get backend module for a specific backend (with explicit override)
+    #
+    # @param explicit_backend [Symbol, String, nil] explicitly requested backend
+    # @return [Module, nil] the backend module or nil if not available
+    # @raise [BackendConflict] if the backend conflicts with previously used backends
+    # @example
+    #   mod = TreeHaver.resolve_backend_module(:ffi)
+    #   mod.capabilities[:backend]  # => :ffi
+    def resolve_backend_module(explicit_backend = nil)
+      # Temporarily override effective backend
+      requested = resolve_effective_backend(explicit_backend)
+
+      mod = case requested
+      when :mri
+        Backends::MRI
+      when :rust
+        Backends::Rust
+      when :ffi
+        Backends::FFI
+      when :java
+        Backends::Java
+      when :citrus
+        Backends::Citrus
+      when :auto
+        backend_module  # Fall back to normal resolution for :auto
+      else
+        # Unknown backend name - return nil to trigger error in caller
+        nil
+      end
+
+      # Return nil if the module doesn't exist
+      return unless mod
+
+      # Check for backend conflicts FIRST, before checking availability
+      # This is critical because the conflict causes the backend to report unavailable
+      # We want to raise a clear error explaining WHY it's unavailable
+      # Use the requested backend name directly (not capabilities) because
+      # capabilities may be empty when the backend is blocked/unavailable
+      check_backend_conflict!(requested) if requested && requested != :auto
+
+      # Now check if the backend is available
+      # Why assume modules without available? are available?
+      # - Some backends might be mocked in tests without an available? method
+      # - This makes the code more defensive and test-friendly
+      # - It allows graceful degradation if a backend module is incomplete
+      # - Backward compatibility: if a module doesn't declare availability, assume it works
+      return if mod.respond_to?(:available?) && !mod.available?
+
+      # Record that this backend is being used
+      record_backend_usage(requested) if requested && requested != :auto
+
+      mod
+    end
+
     # Determine the concrete backend module to use
     #
     # This method performs backend auto-selection when backend is :auto.
-    # On JRuby, prefers Java backend if available, then FFI.
-    # On MRI, prefers MRI backend if available, then Rust, then FFI.
+    # On JRuby, prefers Java backend if available, then FFI, then Citrus.
+    # On MRI, prefers MRI backend if available, then Rust, then FFI, then Citrus.
+    # Citrus is the final fallback as it's pure Ruby and works everywhere.
     #
-    # @return [Module, nil] the backend module (Backends::MRI, Backends::Rust, Backends::FFI, or Backends::Java), or nil if none available
+    # @return [Module, nil] the backend module (Backends::MRI, Backends::Rust, Backends::FFI, Backends::Java, or Backends::Citrus), or nil if none available
     # @example
     #   mod = TreeHaver.backend_module
     #   if mod
     #     puts "Using #{mod.capabilities[:backend]} backend"
     #   end
     def backend_module
-      case backend
+      case effective_backend  # Changed from: backend
       when :mri
         Backends::MRI
       when :rust
@@ -184,8 +517,10 @@ module TreeHaver
         Backends::FFI
       when :java
         Backends::Java
+      when :citrus
+        Backends::Citrus
       else
-        # auto-select: on JRuby prefer Java backend if available; on MRI prefer MRI, then Rust; otherwise FFI
+        # auto-select: prefer native/fast backends, fall back to pure Ruby (Citrus)
         if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" && Backends::Java.available?
           Backends::Java
         elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && Backends::MRI.available?
@@ -194,8 +529,10 @@ module TreeHaver
           Backends::Rust
         elsif Backends::FFI.available?
           Backends::FFI
+        elsif Backends::Citrus.available?
+          Backends::Citrus  # Pure Ruby fallback
         else
-          # No backend available yet
+          # No backend available
           nil
         end
       end
@@ -226,44 +563,102 @@ module TreeHaver
     # Allows opting-in dynamic helpers like TreeHaver::Language.toml without
     # advertising all names by default.
 
-    # Register a language helper by name
+    # Register a language helper by name (backend-agnostic)
     #
     # After registration, you can use dynamic helpers like `TreeHaver::Language.toml`
-    # to load the registered language.
+    # to load the registered language. TreeHaver will automatically use the appropriate
+    # grammar based on the active backend.
+    #
+    # The `name` parameter is an arbitrary identifier you choose - it doesn't need to
+    # match the actual language name. This is useful for:
+    # - Testing: Use unique names like `:toml_test` to avoid collisions
+    # - Aliasing: Register the same grammar under multiple names
+    # - Versioning: Register different grammar versions as `:ruby_2` and `:ruby_3`
+    #
+    # The actual grammar identity comes from `path`/`symbol` (tree-sitter) or
+    # `grammar_module` (Citrus), not from the name.
+    #
+    # IMPORTANT: This method INTENTIONALLY allows registering BOTH a tree-sitter
+    # library AND a Citrus grammar for the same language IN A SINGLE CALL.
+    # This is achieved by using separate `if` statements (not `elsif`) and no early
+    # returns. This design is deliberate and provides significant benefits:
+    #
+    # Why register both backends for one language?
+    # - Backend flexibility: Code works regardless of which backend is active
+    # - Performance testing: Compare tree-sitter vs Citrus performance
+    # - Gradual migration: Transition between backends without breaking code
+    # - Fallback scenarios: Use Citrus when tree-sitter library unavailable
+    # - Platform portability: tree-sitter on Linux/Mac, Citrus on JRuby/Windows
     #
-    # @param name [Symbol, String] language identifier (e.g., :toml, :json)
-    # @param path [String] absolute path to the language shared library
+    # The active backend determines which registration is used automatically.
+    # No code changes needed to switch backends - just change TreeHaver.backend.
+    #
+    # @param name [Symbol, String] identifier for this registration (can be any name you choose)
+    # @param path [String, nil] absolute path to the language shared library (for tree-sitter)
     # @param symbol [String, nil] optional exported factory symbol (e.g., "tree_sitter_toml")
+    # @param grammar_module [Module, nil] Citrus grammar module that responds to .parse(source)
+    # @param gem_name [String, nil] optional gem name for error messages
     # @return [void]
-    # @example Register TOML grammar
+    # @example Register tree-sitter grammar only
     #   TreeHaver.register_language(
     #     :toml,
     #     path: "/usr/local/lib/libtree-sitter-toml.so",
     #     symbol: "tree_sitter_toml"
     #   )
-    def register_language(name, path:, symbol: nil)
-      LanguageRegistry.register(name, path: path, symbol: symbol)
-    end
+    # @example Register Citrus grammar only
+    #   TreeHaver.register_language(
+    #     :toml,
+    #     grammar_module: TomlRB::Document,
+    #     gem_name: "toml-rb"
+    #   )
+    # @example Register BOTH backends in separate calls
+    #   TreeHaver.register_language(
+    #     :toml,
+    #     path: "/usr/local/lib/libtree-sitter-toml.so",
+    #     symbol: "tree_sitter_toml"
+    #   )
+    #   TreeHaver.register_language(
+    #     :toml,
+    #     grammar_module: TomlRB::Document,
+    #     gem_name: "toml-rb"
+    #   )
+    # @example Register BOTH backends in ONE call (recommended for maximum flexibility)
+    #   TreeHaver.register_language(
+    #     :toml,
+    #     path: "/usr/local/lib/libtree-sitter-toml.so",
+    #     symbol: "tree_sitter_toml",
+    #     grammar_module: TomlRB::Document,
+    #     gem_name: "toml-rb"
+    #   )
+    #   # Now TreeHaver::Language.toml works with ANY backend!
+    def register_language(name, path: nil, symbol: nil, grammar_module: nil, gem_name: nil)
+      # Register tree-sitter backend if path provided
+      # Note: Uses `if` not `elsif` so both backends can be registered in one call
+      if path
+        LanguageRegistry.register(name, :tree_sitter, path: path, symbol: symbol)
+      end
 
-    # Unregister a previously registered language helper
-    #
-    # @param name [Symbol, String] language identifier to unregister
-    # @return [void]
-    # @example
-    #   TreeHaver.unregister_language(:toml)
-    def unregister_language(name)
-      LanguageRegistry.unregister(name)
-    end
+      # Register Citrus backend if grammar_module provided
+      # Note: Uses `if` not `elsif` so both backends can be registered in one call
+      # This allows maximum flexibility - register once, use with any backend
+      if grammar_module
+        unless grammar_module.respond_to?(:parse)
+          raise ArgumentError, "Grammar module must respond to :parse"
+        end
 
-    # Clear all registered languages
-    #
-    # Primarily intended for test cleanup and resetting state.
-    #
-    # @return [void]
-    # @example
-    #   TreeHaver.clear_languages!
-    def clear_languages!
-      LanguageRegistry.clear_registrations!
+        LanguageRegistry.register(name, :citrus, grammar_module: grammar_module, gem_name: gem_name)
+      end
+
+      # Require at least one backend to be registered
+      if path.nil? && grammar_module.nil?
+        raise ArgumentError, "Must provide at least one of: path (tree-sitter) or grammar_module (Citrus)"
+      end
+
+      # Note: No early return! This method intentionally processes both `if` blocks
+      # above to allow registering multiple backends for the same language.
+      # Both tree-sitter and Citrus can be registered simultaneously for maximum
+      # flexibility. See method documentation for rationale.
+      nil
     end
 
     # Fetch a registered language entry
@@ -276,7 +671,7 @@ module TreeHaver
     end
   end
 
-  # Represents a Tree-sitter language grammar
+  # Represents a tree-sitter language grammar
   #
   # A Language object is an opaque handle to a TSLanguage* that defines
   # the grammar rules for parsing a specific programming language.
@@ -324,6 +719,7 @@ module TreeHaver
       # @param symbol [String, nil] name of the exported function (defaults to auto-detection)
       # @param name [String, nil] logical name for the language (used in caching)
       # @param validate [Boolean] if true, validates path and symbol for safety (default: true)
+      # @param backend [Symbol, String, nil] optional backend to use (overrides context/global)
       # @return [Language] loaded language handle
       # @raise [NotAvailable] if the library cannot be loaded or the symbol is not found
       # @raise [ArgumentError] if path or symbol fails security validation
@@ -333,7 +729,13 @@ module TreeHaver
       #     symbol: "tree_sitter_toml",
       #     name: "toml"
       #   )
-      def from_library(path, symbol: nil, name: nil, validate: true)
+      # @example With explicit backend
+      #   language = TreeHaver::Language.from_library(
+      #     "/usr/local/lib/libtree-sitter-toml.so",
+      #     symbol: "tree_sitter_toml",
+      #     backend: :ffi
+      #   )
+      def from_library(path, symbol: nil, name: nil, validate: true, backend: nil)
         if validate
           unless PathValidator.safe_library_path?(path)
             errors = PathValidator.validation_errors(path)
@@ -346,11 +748,20 @@ module TreeHaver
           end
         end
 
-        mod = TreeHaver.backend_module
-        raise NotAvailable, "No TreeHaver backend is available" unless mod
+        mod = TreeHaver.resolve_backend_module(backend)
+
+        if mod.nil?
+          if backend
+            raise NotAvailable, "Requested backend #{backend.inspect} is not available"
+          else
+            raise NotAvailable, "No TreeHaver backend is available"
+          end
+        end
+
         # Backend must implement .from_library; fallback to .from_path for older impls
-        # Include ENV vars in cache key since they affect symbol resolution
-        key = [path, symbol, name, ENV["TREE_SITTER_LANG_SYMBOL"]]
+        # Include effective backend AND ENV vars in cache key since they affect loading
+        effective_b = TreeHaver.resolve_effective_backend(backend)
+        key = [effective_b, path, symbol, name, ENV["TREE_SITTER_LANG_SYMBOL"]]
         LanguageRegistry.fetch(key) do
           if mod::Language.respond_to?(:from_library)
             mod::Language.from_library(path, symbol: symbol, name: name)
@@ -366,31 +777,78 @@ module TreeHaver
       # Dynamic helper to load a registered language by name
       #
       # After registering a language with {TreeHaver.register_language},
-      # you can load it using a method call:
+      # you can load it using a method call. The appropriate backend will be
+      # used based on registration and current backend.
       #
-      # @example
+      # @example With tree-sitter
       #   TreeHaver.register_language(:toml, path: "/path/to/libtree-sitter-toml.so")
       #   language = TreeHaver::Language.toml
       #
-      # @example With overrides
-      #   language = TreeHaver::Language.toml(path: "/custom/path.so")
+      # @example With both backends
+      #   TreeHaver.register_language(:toml,
+      #     path: "/path/to/libtree-sitter-toml.so", symbol: "tree_sitter_toml")
+      #   TreeHaver.register_language(:toml,
+      #     grammar_module: TomlRB::Document)
+      #   language = TreeHaver::Language.toml  # Uses appropriate grammar for active backend
       #
       # @param method_name [Symbol] the registered language name
-      # @param args [Array] positional arguments (first is used as path if provided)
-      # @param kwargs [Hash] keyword arguments (:path, :symbol, :name)
+      # @param args [Array] positional arguments
+      # @param kwargs [Hash] keyword arguments
       # @return [Language] loaded language handle
       # @raise [NoMethodError] if the language name is not registered
       def method_missing(method_name, *args, **kwargs, &block)
         # Resolve only if the language name was registered
-        reg = TreeHaver.registered_language(method_name)
-        return super unless reg
-
-        # Allow per-call overrides; otherwise use registered defaults
-        path = kwargs[:path] || args.first || reg[:path]
-        raise ArgumentError, "path is required" unless path
-        symbol = kwargs.key?(:symbol) ? kwargs[:symbol] : (reg[:symbol] || "tree_sitter_#{method_name}")
-        name = kwargs[:name] || method_name.to_s
-        from_library(path, symbol: symbol, name: name)
+        all_backends = TreeHaver.registered_language(method_name)
+        return super unless all_backends
+
+        # Check current backend
+        current_backend = TreeHaver.backend_module
+
+        # Determine which backend type to use
+        backend_type = if current_backend == Backends::Citrus
+          :citrus
+        else
+          :tree_sitter  # MRI, Rust, FFI, Java all use tree-sitter
+        end
+
+        # Get backend-specific registration
+        reg = all_backends[backend_type]
+
+        # If Citrus backend is active
+        if backend_type == :citrus
+          if reg && reg[:grammar_module]
+            return Backends::Citrus::Language.new(reg[:grammar_module])
+          end
+
+          # Fall back to error if no Citrus grammar registered
+          raise NotAvailable,
+            "Citrus backend is active but no Citrus grammar registered for :#{method_name}. " \
+              "Either register a Citrus grammar or use a tree-sitter backend. " \
+              "Registered backends: #{all_backends.keys.inspect}"
+        end
+
+        # For tree-sitter backends, use the path
+        if reg && reg[:path]
+          path = kwargs[:path] || args.first || reg[:path]
+          # Symbol priority: kwargs override > registration > derive from method_name
+          symbol = if kwargs.key?(:symbol)
+            kwargs[:symbol]
+          elsif reg[:symbol]
+            reg[:symbol]
+          else
+            "tree_sitter_#{method_name}"
+          end
+          # Name priority: kwargs override > derive from symbol (strip tree_sitter_ prefix)
+          # Using symbol-derived name ensures ruby_tree_sitter gets the correct language name
+          # e.g., "toml" not "toml_both" when symbol is "tree_sitter_toml"
+          name = kwargs[:name] || symbol&.sub(/\Atree_sitter_/, "")
+          return from_library(path, symbol: symbol, name: name)
+        end
+
+        # No appropriate registration found
+        raise ArgumentError,
+          "No grammar registered for :#{method_name} compatible with #{backend_type} backend. " \
+            "Registered backends: #{all_backends.keys.inspect}"
       end
 
       # @api private
@@ -400,11 +858,34 @@ module TreeHaver
     end
   end
 
-  # Represents a Tree-sitter parser instance
+  # Represents a tree-sitter parser instance
   #
   # A Parser is used to parse source code into a syntax tree. You must
   # set a language before parsing.
   #
+  # == Wrapping/Unwrapping Responsibility
+  #
+  # TreeHaver::Parser is responsible for ALL object wrapping and unwrapping:
+  #
+  # **Language objects:**
+  # - Unwraps Language wrappers before passing to backend.language=
+  # - MRI backend receives ::TreeSitter::Language
+  # - Rust backend receives String (language name)
+  # - FFI backend receives wrapped Language (needs to_ptr)
+  #
+  # **Tree objects:**
+  # - parse() receives raw source, backend returns raw tree, Parser wraps it
+  # - parse_string() unwraps old_tree before passing to backend, wraps returned tree
+  # - Backends always work with raw backend trees, never TreeHaver::Tree
+  #
+  # **Node objects:**
+  # - Backends return raw nodes, TreeHaver::Tree and TreeHaver::Node wrap them
+  #
+  # This design ensures:
+  # - Principle of Least Surprise: wrapping happens at boundaries, consistently
+  # - Backends are simple: they don't need to know about TreeHaver wrappers
+  # - Single Responsibility: wrapping logic is only in TreeHaver::Parser
+  #
   # @example Basic parsing
   #   parser = TreeHaver::Parser.new
   #   parser.language = TreeHaver::Language.toml
@@ -412,11 +893,56 @@ module TreeHaver
   class Parser
     # Create a new parser instance
     #
-    # @raise [NotAvailable] if no backend is available
-    def initialize
-      mod = TreeHaver.backend_module
-      raise NotAvailable, "No TreeHaver backend is available" unless mod
+    # @param backend [Symbol, String, nil] optional backend to use (overrides context/global)
+    # @raise [NotAvailable] if no backend is available or requested backend is unavailable
+    # @example Default (uses context/global)
+    #   parser = TreeHaver::Parser.new
+    # @example Explicit backend
+    #   parser = TreeHaver::Parser.new(backend: :ffi)
+    def initialize(backend: nil)
+      # Convert string backend names to symbols for consistency
+      backend = backend.to_sym if backend.is_a?(String)
+
+      mod = TreeHaver.resolve_backend_module(backend)
+
+      if mod.nil?
+        if backend
+          raise NotAvailable, "Requested backend #{backend.inspect} is not available"
+        else
+          raise NotAvailable, "No TreeHaver backend is available"
+        end
+      end
+
       @impl = mod::Parser.new
+      @explicit_backend = backend  # Remember for introspection (always a Symbol or nil)
+    end
+
+    # Get the backend this parser is using (for introspection)
+    #
+    # Returns the actual backend in use, resolving :auto to the concrete backend.
+    #
+    # @return [Symbol] the backend name (:mri, :rust, :ffi, :java, or :citrus)
+    def backend
+      if @explicit_backend && @explicit_backend != :auto
+        @explicit_backend
+      else
+        # Determine actual backend from the implementation class
+        case @impl.class.name
+        when /MRI/
+          :mri
+        when /Rust/
+          :rust
+        when /FFI/
+          :ffi
+        when /Java/
+          :java
+        when /Citrus/
+          :citrus
+        else
+          # Fallback to effective_backend if we can't determine from class name
+          TreeHaver.effective_backend
+        end
+      end
     end
 
     # Set the language grammar for this parser
@@ -426,9 +952,135 @@ module TreeHaver
     # @example
     #   parser.language = TreeHaver::Language.from_library("/path/to/grammar.so")
     def language=(lang)
-      @impl.language = lang
+      # Unwrap the language before passing to backend
+      # Backends receive raw language objects, never TreeHaver wrappers
+      inner_lang = unwrap_language(lang)
+      @impl.language = inner_lang
+      # Return the original (possibly wrapped) language for consistency
+      lang
     end
 
+    private
+
+    # Unwrap a language object to extract the raw backend language
+    #
+    # This method is smart about backend compatibility:
+    # 1. If language has a backend attribute, checks if it matches current backend
+    # 2. If mismatch detected, attempts to reload language for correct backend
+    # 3. If reload successful, uses new language; otherwise continues with original
+    # 4. Unwraps the language wrapper to get raw backend object
+    #
+    # @param lang [Object] wrapped or raw language object
+    # @return [Object] raw backend language object appropriate for current backend
+    # @api private
+    def unwrap_language(lang)
+      # Check if this is a TreeHaver language wrapper with backend info
+      if lang.respond_to?(:backend)
+        # Verify backend compatibility FIRST
+        # This prevents passing languages from wrong backends to native code
+        # Exception: :auto backend is permissive - accepts any language
+        current_backend = backend
+
+        if lang.backend != current_backend && current_backend != :auto
+          # Backend mismatch! Try to reload for correct backend
+          reloaded = try_reload_language_for_backend(lang, current_backend)
+          if reloaded
+            lang = reloaded
+          else
+            # Couldn't reload - this is an error
+            raise TreeHaver::Error,
+              "Language backend mismatch: language is for #{lang.backend}, parser is #{current_backend}. " \
+                "Cannot reload language for correct backend. " \
+                "Create a new language with TreeHaver::Language.from_library when backend is #{current_backend}."
+          end
+        end
+
+        # Get the current parser's language (if set)
+        current_lang = @impl.respond_to?(:language) ? @impl.language : nil
+
+        # Language mismatch detected! The parser might have a different language set
+        # Compare the actual language objects using Comparable
+        if current_lang && lang != current_lang
+          # Different language being set (e.g., switching from TOML to JSON)
+          # This is fine, just informational
+        end
+      end
+
+      # Unwrap based on backend type
+      # All TreeHaver Language wrappers have the backend attribute
+      unless lang.respond_to?(:backend)
+        # This shouldn't happen - all our wrappers have backend attribute
+        # If we get here, it's likely a raw backend object that was passed directly
+        raise TreeHaver::Error,
+          "Expected TreeHaver Language wrapper with backend attribute, got #{lang.class}. " \
+            "Use TreeHaver::Language.from_library to create language objects."
+      end
+
+      case lang.backend
+      when :mri
+        return lang.to_language if lang.respond_to?(:to_language)
+        return lang.inner_language if lang.respond_to?(:inner_language)
+      when :rust
+        return lang.name if lang.respond_to?(:name)
+      when :ffi
+        return lang  # FFI needs wrapper for to_ptr
+      when :java
+        return lang.impl if lang.respond_to?(:impl)
+      when :citrus
+        return lang.grammar_module if lang.respond_to?(:grammar_module)
+      else
+        # Unknown backend (e.g., test backend)
+        # Try generic unwrapping methods for flexibility in testing
+        return lang.to_language if lang.respond_to?(:to_language)
+        return lang.inner_language if lang.respond_to?(:inner_language)
+        return lang.impl if lang.respond_to?(:impl)
+        return lang.grammar_module if lang.respond_to?(:grammar_module)
+        return lang.name if lang.respond_to?(:name)
+
+        # If nothing works, pass through as-is
+        # This allows test languages to be passed directly
+        return lang
+      end
+
+      # Shouldn't reach here, but just in case
+      lang
+    end
+
+    # Try to reload a language for the current backend
+    #
+    # This handles the case where a language was loaded for one backend,
+    # but is now being used with a different backend (e.g., after backend switch).
+    #
+    # @param lang [Object] language object with metadata
+    # @param target_backend [Symbol] backend to reload for
+    # @return [Object, nil] reloaded language or nil if reload not possible
+    # @api private
+    def try_reload_language_for_backend(lang, target_backend)
+      # Can't reload without path information
+      return unless lang.respond_to?(:path) || lang.respond_to?(:grammar_module)
+
+      # For tree-sitter backends, reload from path
+      if lang.respond_to?(:path) && lang.path
+        begin
+          # Use Language.from_library which respects current backend
+          return Language.from_library(
+            lang.path,
+            symbol: lang.respond_to?(:symbol) ? lang.symbol : nil,
+            name: lang.respond_to?(:name) ? lang.name : nil,
+          )
+        rescue => e
+          # Reload failed, continue with original
+          warn("TreeHaver: Failed to reload language for backend #{target_backend}: #{e.message}") if $VERBOSE
+          return
+        end
+      end
+
+      # For Citrus, can't really reload as it's just a module reference
+      nil
+    end
+
+    public
+
     # Parse source code into a syntax tree
     #
     # @param source [String] the source code to parse (should be UTF-8)
@@ -438,7 +1090,8 @@ module TreeHaver
     #   puts tree.root_node.type
     def parse(source)
       tree_impl = @impl.parse(source)
-      Tree.new(tree_impl)
+      # Wrap backend tree with source so Node#text works
+      Tree.new(tree_impl, source: source)
     end
 
     # Parse source code into a syntax tree (with optional incremental parsing)
@@ -448,7 +1101,7 @@ module TreeHaver
     #
     # == Incremental Parsing
     #
-    # Tree-sitter supports **incremental parsing** where you can pass a previously
+    # tree-sitter supports **incremental parsing** where you can pass a previously
     # parsed tree along with edit information to efficiently re-parse only the
     # changed portions of source code. This is a major performance optimization
     # for editors and IDEs that need to re-parse on every keystroke.
@@ -458,7 +1111,7 @@ module TreeHaver
     # 2. User edits the source (e.g., inserts a character)
     # 3. Call `tree.edit(...)` to update the tree's position data
     # 4. Re-parse with the old tree: `new_tree = parser.parse_string(tree, new_source)`
-    # 5. Tree-sitter reuses unchanged nodes, only re-parsing affected regions
+    # 5. tree-sitter reuses unchanged nodes, only re-parsing affected regions
     #
     # TreeHaver passes through to the underlying backend if it supports incremental
     # parsing (MRI and Rust backends do). Check `TreeHaver.capabilities[:incremental]`
@@ -467,7 +1120,7 @@ module TreeHaver
     # @param old_tree [Tree, nil] previously parsed tree for incremental parsing, or nil for fresh parse
     # @param source [String] the source code to parse (should be UTF-8)
     # @return [Tree] the parsed syntax tree
-    # @see https://tree-sitter.github.io/tree-sitter/using-parsers#editing Tree-sitter incremental parsing docs
+    # @see https://tree-sitter.github.io/tree-sitter/using-parsers#editing tree-sitter incremental parsing docs
     # @see Tree#edit For marking edits before incremental re-parsing
     # @example First parse (no old tree)
     #   tree = parser.parse_string(nil, "x = 1")
@@ -478,12 +1131,21 @@ module TreeHaver
       # Pass through to backend if it supports incremental parsing
       if old_tree && @impl.respond_to?(:parse_string)
         # Extract the underlying implementation from our Tree wrapper
-        old_impl = old_tree.is_a?(Tree) ? old_tree.instance_variable_get(:@impl) : old_tree
+        old_impl = if old_tree.respond_to?(:inner_tree)
+          old_tree.inner_tree
+        elsif old_tree.respond_to?(:instance_variable_get)
+          # Fallback for compatibility
+          old_tree.instance_variable_get(:@inner_tree) || old_tree.instance_variable_get(:@impl) || old_tree
+        else
+          old_tree
+        end
         tree_impl = @impl.parse_string(old_impl, source)
-        Tree.new(tree_impl)
+        # Wrap backend tree with source so Node#text works
+        Tree.new(tree_impl, source: source)
       elsif @impl.respond_to?(:parse_string)
         tree_impl = @impl.parse_string(nil, source)
-        Tree.new(tree_impl)
+        # Wrap backend tree with source so Node#text works
+        Tree.new(tree_impl, source: source)
       else
         # Fallback for backends that don't support parse_string
         parse(source)
@@ -491,219 +1153,13 @@ module TreeHaver
     end
   end
 
-  # Represents a parsed syntax tree
+  # Tree and Node classes have been moved to separate files:
+  # - tree_haver/tree.rb: TreeHaver::Tree - unified wrapper providing consistent API
+  # - tree_haver/node.rb: TreeHaver::Node - unified wrapper providing consistent API
   #
-  # A Tree is the result of parsing source code. It provides access to
-  # the root node of the AST and supports incremental parsing via the
-  # {#edit} method.
-  #
-  # @example Basic usage
-  #   tree = parser.parse(source)
-  #   root = tree.root_node
-  #
-  # @example Incremental parsing
-  #   tree = parser.parse_string(nil, original_source)
-  #   tree.edit(
-  #     start_byte: 10,
-  #     old_end_byte: 15,
-  #     new_end_byte: 20,
-  #     start_point: { row: 0, column: 10 },
-  #     old_end_point: { row: 0, column: 15 },
-  #     new_end_point: { row: 0, column: 20 }
-  #   )
-  #   new_tree = parser.parse_string(tree, edited_source)
-  class Tree
-    # @api private
-    def initialize(impl)
-      @impl = impl
-    end
-
-    # Get the root node of the syntax tree
-    #
-    # @return [Node] the root node
-    # @example
-    #   root = tree.root_node
-    #   puts root.type  # => "document" or similar
-    def root_node
-      Node.new(@impl.root_node)
-    end
-
-    # Mark the tree as edited for incremental re-parsing
-    #
-    # Call this method after the source code has been modified but before
-    # re-parsing. This tells Tree-sitter which parts of the tree are
-    # invalidated so it can efficiently re-parse only the affected regions.
-    #
-    # @param start_byte [Integer] byte offset where the edit starts
-    # @param old_end_byte [Integer] byte offset where the old text ended
-    # @param new_end_byte [Integer] byte offset where the new text ends
-    # @param start_point [Hash] starting position as `{ row:, column: }`
-    # @param old_end_point [Hash] old ending position as `{ row:, column: }`
-    # @param new_end_point [Hash] new ending position as `{ row:, column: }`
-    # @return [void]
-    # @raise [NotAvailable] if the backend doesn't support incremental parsing
-    # @see https://tree-sitter.github.io/tree-sitter/using-parsers#editing
-    #
-    # @example
-    #   # Original: "x = 1"
-    #   # Edited:   "x = 42"  (replaced "1" with "42" at byte 4)
-    #   tree.edit(
-    #     start_byte: 4,
-    #     old_end_byte: 5,
-    #     new_end_byte: 6,
-    #     start_point: { row: 0, column: 4 },
-    #     old_end_point: { row: 0, column: 5 },
-    #     new_end_point: { row: 0, column: 6 }
-    #   )
-    def edit(start_byte:, old_end_byte:, new_end_byte:, start_point:, old_end_point:, new_end_point:)
-      unless @impl.respond_to?(:edit)
-        raise NotAvailable, "Incremental parsing not supported by current backend. " \
-          "Use MRI (ruby_tree_sitter) or Rust (tree_stump) backend."
-      end
-
-      @impl.edit(
-        start_byte: start_byte,
-        old_end_byte: old_end_byte,
-        new_end_byte: new_end_byte,
-        start_point: start_point,
-        old_end_point: old_end_point,
-        new_end_point: new_end_point,
-      )
-    end
-
-    # Check if the underlying implementation supports incremental parsing
-    #
-    # @return [Boolean] true if {#edit} can be called on this tree
-    def supports_editing?
-      @impl.respond_to?(:edit)
-    end
-  end
-
-  # Represents a node in the syntax tree
-  #
-  # A Node represents a single element in the parsed AST. Each node has
-  # a type (like "string", "number", "table", etc.) and may have child nodes.
-  #
-  # @example Traversing nodes
-  #   root = tree.root_node
-  #   root.each do |child|
-  #     puts "Child type: #{child.type}"
-  #     child.each { |grandchild| puts "  Grandchild: #{grandchild.type}" }
-  #   end
-  class Node
-    # @api private
-    def initialize(impl)
-      @impl = impl
-    end
-
-    # Get the type name of this node
-    #
-    # The type corresponds to the grammar rule that produced this node
-    # (e.g., "document", "table", "string_literal", "pair", etc.).
-    #
-    # @return [String] the node type
-    # @example
-    #   node.type  # => "table"
-    def type
-      @impl.type
-    end
-
-    # Iterate over child nodes
-    #
-    # @yieldparam child [Node] each child node
-    # @return [Enumerator, nil] an enumerator if no block given, nil otherwise
-    # @example With a block
-    #   node.each { |child| puts child.type }
-    #
-    # @example Without a block
-    #   children = node.each.to_a
-    def each(&blk)
-      return enum_for(:each) unless block_given?
-      @impl.each { |child_impl| blk.call(Node.new(child_impl)) }
-    end
-
-    # Get the start position of this node in the source
-    #
-    # @return [Object] point object with row and column
-    # @example
-    #   node.start_point.row     # => 0
-    #   node.start_point.column  # => 4
-    def start_point
-      @impl.start_point
-    end
-
-    # Get the end position of this node in the source
-    #
-    # @return [Object] point object with row and column
-    # @example
-    #   node.end_point.row     # => 0
-    #   node.end_point.column  # => 10
-    def end_point
-      @impl.end_point
-    end
-
-    # Get the start byte offset of this node in the source
-    #
-    # @return [Integer] byte offset from beginning of source
-    def start_byte
-      @impl.start_byte
-    end
-
-    # Get the end byte offset of this node in the source
-    #
-    # @return [Integer] byte offset from beginning of source
-    def end_byte
-      @impl.end_byte
-    end
-
-    # Check if this node or any descendant has a parse error
-    #
-    # @return [Boolean] true if there is an error in the subtree
-    def has_error?
-      @impl.respond_to?(:has_error?) && @impl.has_error?
-    end
-
-    # Check if this node is a MISSING node (inserted by error recovery)
-    #
-    # @return [Boolean] true if this is a missing node
-    def missing?
-      @impl.respond_to?(:missing?) && @impl.missing?
-    end
-
-    # Get string representation of this node
-    #
-    # @return [String] string representation
-    def to_s
-      @impl.to_s
-    end
-
-    # Check if node responds to a method (includes delegation to @impl)
-    #
-    # @param method_name [Symbol] method to check
-    # @param include_private [Boolean] include private methods
-    # @return [Boolean]
-    def respond_to_missing?(method_name, include_private = false)
-      @impl.respond_to?(method_name, include_private) || super
-    end
-
-    # Delegate unknown methods to the underlying implementation
-    #
-    # This provides full compatibility with ruby_tree_sitter nodes
-    # for methods not explicitly wrapped.
-    #
-    # @param method_name [Symbol] method to call
-    # @param args [Array] arguments to pass
-    # @param block [Proc] block to pass
-    # @return [Object] result from the underlying implementation
-    def method_missing(method_name, *args, **kwargs, &block)
-      if @impl.respond_to?(method_name)
-        @impl.public_send(method_name, *args, **kwargs, &block)
-      else
-        super
-      end
-    end
-  end
-end
+  # These provide a unified interface across all backends (MRI, Rust, FFI, Java, Citrus).
+  # All backends now return properly wrapped TreeHaver::Tree and TreeHaver::Node objects.
+end # end module TreeHaver
 
 TreeHaver::Version.class_eval do
   extend VersionGem::Basic