tree_haver 3.1.2 → 3.2.1

data/lib/tree_haver.rb

@@ -6,20 +6,41 @@ require "version_gem"
 # Standard library
 require "set"
 
-# This gem
+# This gem - only version can be required (never autoloaded)
 require_relative "tree_haver/version"
-require_relative "tree_haver/language_registry"
 
 # TreeHaver is a cross-Ruby adapter for code parsing with 10 backends.
 #
 # Provides a unified API for parsing source code across MRI Ruby, JRuby, and TruffleRuby
 # using tree-sitter grammars or language-specific native parsers.
 #
+# == Backends
+#
 # Supports 10 backends:
 # - Tree-sitter: MRI (C), Rust, FFI, Java
 # - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
 # - Pure Ruby: Citrus (portable fallback)
 #
+# == Platform Compatibility
+#
+# Not all backends work on all Ruby platforms:
+#
+#   | Backend      | MRI | JRuby | TruffleRuby |
+#   |--------------|-----|-------|-------------|
+#   | MRI (C ext)  | ✓   | ✗     | ✗           |
+#   | Rust         | ✓   | ✗     | ✗           |
+#   | FFI          | ✓   | ✓     | ✗           |
+#   | Java         | ✗   | ✓     | ✗           |
+#   | Prism        | ✓   | ✓     | ✓           |
+#   | Psych        | ✓   | ✓     | ✓           |
+#   | Citrus       | ✓   | ✓     | ✓           |
+#   | Commonmarker | ✓   | ✗     | ?           |
+#   | Markly       | ✓   | ✗     | ?           |
+#
+# - JRuby: Cannot load native C/Rust extensions; use FFI, Java, or pure Ruby backends
+# - TruffleRuby: FFI doesn't support STRUCT_BY_VALUE; magnus/rb-sys incompatible with C API;
+#   use Prism, Psych, Citrus, or potentially Commonmarker/Markly
+#
 # @example Basic usage with tree-sitter
 #   # Load a language grammar
 #   language = TreeHaver::Language.from_library(
@@ -84,6 +105,10 @@ require_relative "tree_haver/language_registry"
 # @see GrammarFinder For automatic grammar library discovery
 # @see Backends For available parsing backends
 module TreeHaver
+  # Autoload internal modules
+  autoload :LibraryPathUtils, File.join(__dir__, "tree_haver", "library_path_utils")
+  autoload :LanguageRegistry, File.join(__dir__, "tree_haver", "language_registry")
+
   # Base error class for TreeHaver exceptions
   # @see https://github.com/Faveod/ruby-tree-sitter/pull/83 for inherit from Exception reasoning
   #
@@ -131,6 +156,20 @@ module TreeHaver
   #   # Now you can test backend conflicts (at risk of segfaults)
   class BackendConflict < Error; end
 
+  # Default Citrus configurations for known languages
+  #
+  # These are used by {TreeHaver.parser_for} when no explicit citrus_config is provided
+  # and tree-sitter backends are not available (e.g., on TruffleRuby).
+  #
+  # @api private
+  CITRUS_DEFAULTS = {
+    toml: {
+      gem_name: "toml-rb",
+      grammar_const: "TomlRB::Document",
+      require_path: "toml-rb",
+    },
+  }.freeze
+
   # Namespace for backend implementations
   #
   # TreeHaver provides multiple backends to support different Ruby implementations:
@@ -221,6 +260,12 @@ module TreeHaver
   # Unified Tree wrapper providing consistent API across backends
   autoload :Tree, File.join(__dir__, "tree_haver", "tree")
 
+  # Language class for loading grammar shared libraries
+  autoload :Language, File.join(__dir__, "tree_haver", "language")
+
+  # Parser class for parsing source code into syntax trees
+  autoload :Parser, File.join(__dir__, "tree_haver", "parser")
+
   # Get the current backend selection
   #
   # @return [Symbol] one of :auto, :mri, :rust, :ffi, :java, or :citrus
@@ -545,6 +590,66 @@ module TreeHaver
       mod
     end
 
+    # Native tree-sitter backends that support loading shared libraries (.so files)
+    # These backends wrap the tree-sitter C library via various bindings.
+    # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are excluded.
+    NATIVE_BACKENDS = %i[mri rust ffi java].freeze
+
+    # Resolve a native tree-sitter backend module (for from_library)
+    #
+    # This method is similar to resolve_backend_module but ONLY considers
+    # backends that support loading shared libraries (.so files):
+    # - MRI (ruby_tree_sitter C extension)
+    # - Rust (tree_stump)
+    # - FFI (ffi gem with libtree-sitter)
+    # - Java (jtreesitter on JRuby)
+    #
+    # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are NOT
+    # considered because they don't support from_library.
+    #
+    # @param explicit_backend [Symbol, String, nil] explicitly requested backend
+    # @return [Module, nil] the backend module or nil if none available
+    # @raise [BackendConflict] if the backend conflicts with previously used backends
+    def resolve_native_backend_module(explicit_backend = nil)
+      # Short-circuit on TruffleRuby: no native backends work
+      # - MRI: C extension, MRI only
+      # - Rust: magnus requires MRI's C API
+      # - FFI: STRUCT_BY_VALUE not supported
+      # - Java: requires JRuby's Java interop
+      if defined?(RUBY_ENGINE) && RUBY_ENGINE == "truffleruby"
+        return unless explicit_backend # Auto-select: no backends available
+        # If explicit backend requested, let it fail with proper error below
+      end
+
+      # Get the effective backend (considers thread-local and global settings)
+      requested = resolve_effective_backend(explicit_backend)
+
+      # If the effective backend is a native backend, use it
+      if NATIVE_BACKENDS.include?(requested)
+        return resolve_backend_module(requested)
+      end
+
+      # If a specific non-native backend was explicitly requested, return nil
+      # (from_library only works with native backends that load .so files)
+      return if explicit_backend
+
+      # If effective backend is :auto, auto-select from native backends in priority order
+      # Note: non-native backends set via with_backend are NOT used here because
+      # from_library only works with native backends
+      native_priority = if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby"
+        %i[java ffi] # JRuby: Java first, then FFI
+      else
+        %i[mri rust ffi] # MRI: MRI first, then Rust, then FFI
+      end
+
+      native_priority.each do |backend|
+        mod = resolve_backend_module(backend)
+        return mod if mod
+      end
+
+      nil # No native backend available
+    end
+
     # Determine the concrete backend module to use
     #
     # This method performs backend auto-selection when backend is :auto.
@@ -804,19 +909,25 @@ module TreeHaver
 
       # Step 3: Try Citrus fallback if tree-sitter failed
       unless language
-        citrus_config ||= {}
-        begin
-          citrus_finder = CitrusGrammarFinder.new(
-            language: name,
-            gem_name: citrus_config[:gem_name],
-            grammar_const: citrus_config[:grammar_const],
-          )
-          if citrus_finder.available?
-            citrus_finder.register!
-            language = Language.public_send(name)
+        # Use explicit config, or fall back to built-in defaults for known languages
+        citrus_config ||= CITRUS_DEFAULTS[name] || {}
+
+        # Only attempt if we have the required configuration
+        if citrus_config[:gem_name] && citrus_config[:grammar_const]
+          begin
+            citrus_finder = CitrusGrammarFinder.new(
+              language: name,
+              gem_name: citrus_config[:gem_name],
+              grammar_const: citrus_config[:grammar_const],
+              require_path: citrus_config[:require_path],
+            )
+            if citrus_finder.available?
+              citrus_finder.register!
+              language = Language.public_send(name)
+            end
+          rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
+            language = nil
           end
-        rescue NotAvailable, ArgumentError, LoadError, NameError
-          language = nil
         end
       end
 
@@ -835,552 +946,9 @@ module TreeHaver
     end
   end
 
-  # 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.
-  #
-  # @example Load a language from a shared library
-  #   language = TreeHaver::Language.from_library(
-  #     "/usr/local/lib/libtree-sitter-toml.so",
-  #     symbol: "tree_sitter_toml"
-  #   )
-  #
-  # @example Use a registered language
-  #   TreeHaver.register_language(:toml, path: "/path/to/libtree-sitter-toml.so")
-  #   language = TreeHaver::Language.toml
-  class Language
-    class << self
-      # Load a language grammar from a shared library (ruby_tree_sitter compatibility)
-      #
-      # This method provides API compatibility with ruby_tree_sitter which uses
-      # `Language.load(name, path)`.
-      #
-      # @param name [String] the language name (e.g., "toml")
-      # @param path [String] absolute path to the language shared library
-      # @param validate [Boolean] if true, validates the path for safety (default: true)
-      # @return [Language] loaded language handle
-      # @raise [NotAvailable] if the library cannot be loaded
-      # @raise [ArgumentError] if the path fails security validation
-      # @example
-      #   language = TreeHaver::Language.load("toml", "/usr/local/lib/libtree-sitter-toml.so")
-      def load(name, path, validate: true)
-        from_library(path, symbol: "tree_sitter_#{name}", name: name, validate: validate)
-      end
-
-      # Load a language grammar from a shared library
-      #
-      # The library must export a function that returns a pointer to a TSLanguage struct.
-      # By default, TreeHaver looks for a symbol named "tree_sitter_<name>".
-      #
-      # == Security
-      #
-      # By default, paths are validated using {PathValidator} to prevent path traversal
-      # and other attacks. Set `validate: false` to skip validation (not recommended
-      # unless you've already validated the path).
-      #
-      # @param path [String] absolute path to the language shared library (.so/.dylib/.dll)
-      # @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
-      # @example
-      #   language = TreeHaver::Language.from_library(
-      #     "/usr/local/lib/libtree-sitter-toml.so",
-      #     symbol: "tree_sitter_toml",
-      #     name: "toml"
-      #   )
-      # @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)
-            raise ArgumentError, "Unsafe library path: #{path.inspect}. Errors: #{errors.join("; ")}"
-          end
-
-          if symbol && !PathValidator.safe_symbol_name?(symbol)
-            raise ArgumentError, "Unsafe symbol name: #{symbol.inspect}. " \
-              "Symbol names must be valid C identifiers."
-          end
-        end
-
-        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 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)
-          else
-            mod::Language.from_path(path)
-          end
-        end
-      end
-      # Alias for {from_library}
-      # @see from_library
-      alias_method :from_path, :from_library
-
-      # 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. The appropriate backend will be
-      # used based on registration and current backend.
-      #
-      # @example With tree-sitter
-      #   TreeHaver.register_language(:toml, path: "/path/to/libtree-sitter-toml.so")
-      #   language = TreeHaver::Language.toml
-      #
-      # @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
-      # @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
-        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, try to load from path
-        # If that fails, fall back to Citrus if available
-        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_/, "")
-
-          begin
-            return from_library(path, symbol: symbol, name: name)
-          rescue NotAvailable, ArgumentError, LoadError, FFI::NotFoundError => _e
-            # Tree-sitter failed to load - check for Citrus fallback
-            # This handles cases where:
-            # - The .so file doesn't exist or can't be loaded (NotAvailable, LoadError)
-            # - FFI can't find required symbols like ts_parser_new (FFI::NotFoundError)
-            # - Invalid arguments were provided (ArgumentError)
-            citrus_reg = all_backends[:citrus]
-            if citrus_reg && citrus_reg[:grammar_module]
-              return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
-            end
-            # No Citrus fallback available, re-raise the original error
-            raise
-          end
-        end
-
-        # No tree-sitter path registered - check for Citrus fallback
-        # This enables auto-fallback when tree-sitter grammar is not installed
-        # but a Citrus grammar (pure Ruby) is available
-        citrus_reg = all_backends[:citrus]
-        if citrus_reg && citrus_reg[:grammar_module]
-          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
-        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
-      def respond_to_missing?(method_name, include_private = false)
-        !!TreeHaver.registered_language(method_name) || super
-      end
-    end
-  end
-
-  # 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
-  #   tree = parser.parse("[package]\nname = \"foo\"")
-  class Parser
-    # Create a new parser instance
-    #
-    # @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
-
-      # Try to create the parser, with fallback to Citrus if tree-sitter fails
-      # This enables auto-fallback when tree-sitter runtime isn't available
-      begin
-        @impl = mod::Parser.new
-        @explicit_backend = backend  # Remember for introspection (always a Symbol or nil)
-      rescue NoMethodError, FFI::NotFoundError, LoadError => e
-        # Tree-sitter backend failed (likely missing runtime library)
-        # Try Citrus as fallback if we weren't explicitly asked for a specific backend
-        if backend.nil? || backend == :auto
-          if Backends::Citrus.available?
-            @impl = Backends::Citrus::Parser.new
-            @explicit_backend = :citrus
-          else
-            # No fallback available, re-raise original error
-            raise NotAvailable, "Tree-sitter backend failed: #{e.message}. " \
-              "Citrus fallback not available. Install tree-sitter runtime or citrus gem."
-          end
-        else
-          # Explicit backend was requested, don't fallback
-          raise
-        end
-      end
-    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
-    #
-    # @param lang [Language] the language to use for parsing
-    # @return [Language] the language that was set
-    # @example
-    #   parser.language = TreeHaver::Language.from_library("/path/to/grammar.so")
-    def language=(lang)
-      # Check if this is a Citrus language - if so, we need a Citrus parser
-      # This enables automatic backend switching when tree-sitter fails and
-      # falls back to Citrus
-      if lang.is_a?(Backends::Citrus::Language)
-        unless @impl.is_a?(Backends::Citrus::Parser)
-          # Switch to Citrus parser to match the Citrus language
-          @impl = Backends::Citrus::Parser.new
-          @explicit_backend = :citrus
-        end
-      end
-
-      # 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 # rubocop:disable Lint/Void (intentional return value)
-    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)
-      when :prism
-        return lang  # Prism backend expects the Language wrapper
-      when :psych
-        return lang  # Psych backend expects the Language wrapper
-      when :commonmarker
-        return lang  # Commonmarker backend expects the Language wrapper
-      when :markly
-        return lang  # Markly backend expects the Language wrapper
-      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)
-    # @return [Tree] the parsed syntax tree
-    # @example
-    #   tree = parser.parse("x = 1")
-    #   puts tree.root_node.type
-    def parse(source)
-      tree_impl = @impl.parse(source)
-      # 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)
-    #
-    # This method provides API compatibility with ruby_tree_sitter which uses
-    # `parse_string(old_tree, source)`.
-    #
-    # == Incremental Parsing
-    #
-    # 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.
-    #
-    # The workflow for incremental parsing is:
-    # 1. Parse the initial source: `tree = parser.parse_string(nil, source)`
-    # 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
-    #
-    # TreeHaver passes through to the underlying backend if it supports incremental
-    # parsing (MRI and Rust backends do). Check `TreeHaver.capabilities[:incremental]`
-    # to see if the current backend supports it.
-    #
-    # @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 Tree#edit For marking edits before incremental re-parsing
-    # @example First parse (no old tree)
-    #   tree = parser.parse_string(nil, "x = 1")
-    # @example Incremental parse
-    #   tree.edit(start_byte: 4, old_end_byte: 5, new_end_byte: 6, ...)
-    #   new_tree = parser.parse_string(tree, "x = 42")
-    def parse_string(old_tree, source)
-      # 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 = 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)
-        # 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)
-        # 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)
-      end
-    end
-  end
-
-  # Tree and Node classes have been moved to separate files:
+  # Language and Parser classes have been moved to separate files:
+  # - tree_haver/language.rb: TreeHaver::Language - loads grammar shared libraries
+  # - tree_haver/parser.rb: TreeHaver::Parser - parses source code into syntax trees
   # - tree_haver/tree.rb: TreeHaver::Tree - unified wrapper providing consistent API
   # - tree_haver/node.rb: TreeHaver::Node - unified wrapper providing consistent API
   #