tree_haver 3.1.2 → 3.2.0

data/lib/tree_haver/backends/citrus.rb

@@ -451,8 +451,14 @@ module TreeHaver
         private
 
         def calculate_point(offset)
+          return {row: 0, column: 0} if offset <= 0
+
           lines_before = @source[0...offset].count("\n")
-          line_start = @source.rindex("\n", offset - 1) || -1
+          # Find the newline before this offset (or -1 if we're on line 0)
+          line_start = if offset > 0
+            @source.rindex("\n", offset - 1)
+          end
+          line_start ||= -1
           column = offset - line_start - 1
           {row: lines_before, column: column}
         end

data/lib/tree_haver/backends/ffi.rb

@@ -5,8 +5,7 @@ module TreeHaver
     # FFI-based backend for calling libtree-sitter directly
     #
     # This backend uses Ruby FFI (JNR-FFI on JRuby) to call the native tree-sitter
-    # C library without requiring MRI C extensions. This makes it compatible with
-    # JRuby, TruffleRuby, and other Ruby implementations that support FFI.
+    # C library without requiring MRI C extensions.
     #
     # The FFI backend currently supports:
     # - Parsing source code
@@ -16,28 +15,85 @@ module TreeHaver
     # Not yet supported:
     # - Query API (tree-sitter queries/patterns)
     #
+    # == Platform Compatibility
+    #
+    # - MRI Ruby: ✓ Full support
+    # - JRuby: ✓ Full support (uses JNR-FFI)
+    # - TruffleRuby: ✗ TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
+    #   (used by ts_tree_root_node, ts_node_child, ts_node_start_point, etc.)
+    #
     # @note Requires the `ffi` gem and libtree-sitter shared library to be installed
     # @see https://github.com/ffi/ffi Ruby FFI
     # @see https://tree-sitter.github.io/tree-sitter/ tree-sitter
     module FFI
-      # Check if the FFI gem is available (lazy evaluation)
+      # Module-level availability and capability methods
       #
-      # This method lazily checks for FFI gem availability to avoid
-      # polluting the environment at load time.
+      # These methods provide API consistency with other backends.
       class << self
-        # Check if the FFI gem can be loaded
-        # @return [Boolean] true if FFI gem can be loaded
+        # Check if the FFI backend is available
+        #
+        # The FFI backend requires:
+        # - The ffi gem to be installed
+        # - NOT running on TruffleRuby (STRUCT_BY_VALUE limitation)
+        # - MRI backend (ruby_tree_sitter) not already loaded (symbol conflicts)
+        #
+        # @return [Boolean] true if FFI backend can be used
+        # @example
+        #   if TreeHaver::Backends::FFI.available?
+        #     puts "FFI backend is ready"
+        #   end
+        def available?
+          return false unless ffi_gem_available?
+
+          # Check if MRI backend has been loaded (which blocks FFI)
+          !defined?(::TreeSitter::Parser)
+        end
+
+        # Check if the FFI gem can be loaded and is usable for tree-sitter
+        #
+        # @return [Boolean] true if FFI gem can be loaded and works with tree-sitter
         # @api private
+        # @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 @ffi_gem_available if defined?(@ffi_gem_available)
 
           @ffi_gem_available = begin
+            # 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
           rescue LoadError
             false
           end
         end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @ffi_gem_available = nil
+        end
+
+        # Get capabilities supported by this backend
+        #
+        # @return [Hash{Symbol => Object}] capability map
+        # @example
+        #   TreeHaver::Backends::FFI.capabilities
+        #   # => { backend: :ffi, parse: true, query: false, bytes_field: true }
+        def capabilities
+          return {} unless available?
+          {
+            backend: :ffi,
+            parse: true,
+            query: false, # Query API not yet implemented in FFI backend
+            bytes_field: true,
+            incremental: false,
+          }
+        end
       end
 
       # Native FFI bindings to libtree-sitter
@@ -151,15 +207,16 @@ module TreeHaver
 
             last_error = nil
             candidates = lib_candidates
+            lib_loaded = false
             candidates.each do |name|
               ffi_lib(name)
-              @loaded = true
+              lib_loaded = true
               break
             rescue ::FFI::NotFoundError, LoadError => e
               last_error = e
             end
 
-            unless @loaded
+            unless lib_loaded
               # :nocov:
               tried = candidates.join(", ")
               env_hint = ENV["TREE_SITTER_RUNTIME_LIB"] ? " TREE_SITTER_RUNTIME_LIB=#{ENV["TREE_SITTER_RUNTIME_LIB"]}." : ""
@@ -173,6 +230,8 @@ module TreeHaver
             end
 
             # Attach functions after lib is selected
+            # Note: TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types,
+            # so these attach_function calls will fail on TruffleRuby.
             attach_function(:ts_parser_new, [], :pointer)
             attach_function(:ts_parser_delete, [:pointer], :void)
             attach_function(:ts_parser_set_language, [:pointer, :pointer], :bool)
@@ -190,6 +249,9 @@ module TreeHaver
             attach_function(:ts_node_end_point, [:ts_node], :ts_point)
             attach_function(:ts_node_is_null, [:ts_node], :bool)
             attach_function(:ts_node_is_named, [:ts_node], :bool)
+
+            # Only mark as fully loaded after all attach_function calls succeed
+            @loaded = true
           end
 
           def loaded?
@@ -198,57 +260,6 @@ module TreeHaver
         end
       end
 
-      class << self
-        # Check if the FFI backend is available
-        #
-        # Returns true if:
-        # 1. The `ffi` gem is present
-        # 2. MRI backend (ruby_tree_sitter) has NOT been loaded
-        #
-        # FFI and MRI backends conflict at the libtree-sitter level.
-        # Once MRI loads, using FFI will cause segfaults.
-        #
-        # @return [Boolean] true if FFI backend can be used
-        # @example
-        #   if TreeHaver::Backends::FFI.available?
-        #     puts "FFI backend is ready"
-        #   end
-        def available?
-          return false unless TreeHaver::Backends::FFI.ffi_gem_available?
-
-          # Check if MRI backend has been loaded (which blocks FFI)
-          !defined?(::TreeSitter::Parser)
-        end
-
-        # Reset the load state (primarily for testing)
-        #
-        # Note: FFI backend doesn't maintain load state like other backends,
-        # but this method is provided for API consistency.
-        #
-        # @return [void]
-        # @api private
-        def reset!
-          # FFI backend uses constant-time availability check, no state to reset
-          nil
-        end
-
-        # Get capabilities supported by this backend
-        #
-        # @return [Hash{Symbol => Object}] capability map
-        # @example
-        #   TreeHaver::Backends::FFI.capabilities
-        #   # => { backend: :ffi, parse: true, query: false, bytes_field: true }
-        def capabilities
-          return {} unless available?
-          {
-            backend: :ffi,
-            parse: true,
-            query: false,
-            bytes_field: true,
-          }
-        end
-      end
-
       # Represents a tree-sitter language loaded via FFI
       #
       # Holds a pointer to a TSLanguage struct from a loaded shared library.
@@ -378,7 +389,8 @@ module TreeHaver
               end
 
               dl = ::FFI::DynamicLibrary.open(path, flags)
-            rescue LoadError => e
+            rescue LoadError, RuntimeError => e
+              # TruffleRuby raises RuntimeError instead of LoadError when a shared library cannot be opened
               raise TreeHaver::NotAvailable, "Could not open language library at #{path}: #{e.message}"
             end
 

data/lib/tree_haver/backends/java.rb

@@ -13,6 +13,12 @@ module TreeHaver
     # - The Query API for pattern matching
     # - Tree editing for incremental re-parsing
     #
+    # == Platform Compatibility
+    #
+    # - MRI Ruby: ✗ Not available (no JVM)
+    # - JRuby: ✓ Full support (native Java integration)
+    # - TruffleRuby: ✗ Not available (java-tree-sitter requires JRuby's Java interop)
+    #
     # == Installation
     #
     # 1. Download the JAR from Maven Central:
@@ -24,7 +30,6 @@ module TreeHaver
     # 3. Use JRuby to run your code:
     #    jruby -e "require 'tree_haver'; puts TreeHaver::Backends::Java.available?"
     #
-    # @note Only available on JRuby
     # @see https://github.com/tree-sitter/java-tree-sitter source
     # @see https://tree-sitter.github.io/java-tree-sitter java-tree-sitter documentation
     # @see https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter Maven Central

data/lib/tree_haver/backends/mri.rb

@@ -8,7 +8,12 @@ module TreeHaver
     # for MRI Ruby. It provides the most feature-complete tree-sitter integration
     # on MRI, including support for the Query API.
     #
-    # @note This backend only works on MRI Ruby, not JRuby or TruffleRuby
+    # == Platform Compatibility
+    #
+    # - MRI Ruby: ✓ Full support (fastest tree-sitter backend on MRI)
+    # - JRuby: ✗ Cannot load native C extensions (runs on JVM)
+    # - TruffleRuby: ✗ C extension not compatible with TruffleRuby
+    #
     # @see https://github.com/Faveod/ruby-tree-sitter ruby_tree_sitter
     module MRI
       @load_attempted = false
@@ -37,6 +42,14 @@ module TreeHaver
         def available?
           return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
           @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+          # ruby_tree_sitter is a C extension that only works on MRI
+          # It doesn't work on JRuby or TruffleRuby
+          unless RUBY_ENGINE == "ruby"
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            return @loaded
+          end
+
           begin
             require "tree_sitter" # Note: gem is ruby_tree_sitter but requires tree_sitter
 

data/lib/tree_haver/backends/rust.rb

@@ -11,7 +11,12 @@ module TreeHaver
     # tree_stump supports incremental parsing and the Query API, making it
     # suitable for editor/IDE use cases where performance is critical.
     #
-    # @note This backend works on MRI Ruby. JRuby/TruffleRuby support is unknown.
+    # == Platform Compatibility
+    #
+    # - MRI Ruby: ✓ Full support
+    # - JRuby: ✗ Cannot load native extensions (runs on JVM)
+    # - TruffleRuby: ✗ magnus/rb-sys incompatible with TruffleRuby's C API emulation
+    #
     # @see https://github.com/joker1007/tree_stump tree_stump
     module Rust
       @load_attempted = false
@@ -30,6 +35,14 @@ module TreeHaver
         def available?
           return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
           @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+          # tree_stump uses magnus which requires MRI's C API
+          # It doesn't work on JRuby or TruffleRuby
+          unless RUBY_ENGINE == "ruby"
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            return @loaded
+          end
+
           begin
             require "tree_stump"
 

data/lib/tree_haver/citrus_grammar_finder.rb

@@ -46,12 +46,12 @@ module TreeHaver
     # @param language [Symbol, String] the language name (e.g., :toml, :json)
     # @param gem_name [String] the gem name (e.g., "toml-rb")
     # @param grammar_const [String] constant path to grammar (e.g., "TomlRB::Document")
-    # @param require_path [String, nil] custom require path (defaults to gem_name with dashes→slashes)
+    # @param require_path [String, nil] custom require path (defaults to gem_name as-is)
     def initialize(language:, gem_name:, grammar_const:, require_path: nil)
       @language_name = language.to_sym
       @gem_name = gem_name
       @grammar_const = grammar_const
-      @require_path = require_path || gem_name.tr("-", "/")
+      @require_path = require_path || gem_name
       @load_attempted = false
       @available = false
       @grammar_module = nil
@@ -67,6 +67,15 @@ module TreeHaver
       return @available if @load_attempted
 
       @load_attempted = true
+      debug = ENV["TREE_HAVER_DEBUG"]
+
+      # Guard against nil require_path (can happen if gem_name was nil)
+      if @require_path.nil? || @require_path.empty?
+        warn("CitrusGrammarFinder: require_path is nil or empty for #{@language_name}") if debug
+        @available = false
+        return false
+      end
+
       begin
         # Try to require the gem
         require @require_path
@@ -76,25 +85,64 @@ module TreeHaver
 
         # Verify it responds to parse
         unless @grammar_module.respond_to?(:parse)
-          warn("#{@grammar_const} doesn't respond to :parse")
+          # :nocov: defensive - requires a gem with malformed grammar module
+          # Show what methods ARE available to help diagnose the issue
+          if debug
+            available_methods = @grammar_module.methods(false).sort.first(20)
+            warn("CitrusGrammarFinder: #{@grammar_const} doesn't respond to :parse")
+            warn("CitrusGrammarFinder: #{@grammar_const}.class = #{@grammar_module.class}")
+            warn("CitrusGrammarFinder: #{@grammar_const} is a #{@grammar_module.is_a?(Module) ? "Module" : "non-Module"}")
+            warn("CitrusGrammarFinder: Available singleton methods (first 20): #{available_methods.inspect}")
+            if @grammar_module.respond_to?(:instance_methods)
+              instance_methods = @grammar_module.instance_methods(false).sort.first(20)
+              warn("CitrusGrammarFinder: Available instance methods (first 20): #{instance_methods.inspect}")
+            end
+          end
           @available = false
           return false
+          # :nocov:
         end
 
         @available = true
       rescue LoadError => e
-        # Always show LoadError for debugging
-        warn("CitrusGrammarFinder: Failed to load '#{@require_path}': #{e.class}: #{e.message}")
+        # :nocov: defensive - requires gem to not be installed
+        # Only show LoadError details when debugging
+        if debug
+          warn("CitrusGrammarFinder: Failed to load '#{@require_path}': #{e.class}: #{e.message}")
+          warn("CitrusGrammarFinder: LoadError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
         @available = false
+        # :nocov:
       rescue NameError => e
-        # Always show NameError for debugging
-        warn("CitrusGrammarFinder: Failed to resolve '#{@grammar_const}': #{e.class}: #{e.message}")
+        # :nocov: defensive - requires gem with missing constant
+        # Only show NameError details when debugging
+        if debug
+          warn("CitrusGrammarFinder: Failed to resolve '#{@grammar_const}': #{e.class}: #{e.message}")
+          warn("CitrusGrammarFinder: NameError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
         @available = false
+        # :nocov:
+      rescue TypeError => e
+        # :nocov: defensive - TruffleRuby-specific edge case
+        # TruffleRuby's bundled_gems.rb can raise TypeError when File.path is called on nil
+        # This happens in bundled_gems.rb:124 warning? method when caller locations return nil
+        # Always warn about TypeError as it indicates a platform-specific issue
+        warn("CitrusGrammarFinder: TypeError during load of '#{@require_path}': #{e.class}: #{e.message}")
+        warn("CitrusGrammarFinder: This may be a TruffleRuby bundled_gems.rb issue")
+        if debug
+          warn("CitrusGrammarFinder: TypeError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
+        @available = false
+        # :nocov:
       rescue => e
-        # Catch any other errors
+        # :nocov: defensive - catch-all for unexpected errors
+        # Always warn about unexpected errors
         warn("CitrusGrammarFinder: Unexpected error: #{e.class}: #{e.message}")
-        warn(e.backtrace.first(3).join("\n")) if ENV["TREE_HAVER_DEBUG"]
+        if debug
+          warn("CitrusGrammarFinder: backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
+        end
         @available = false
+        # :nocov:
       end
 
       @available

data/lib/tree_haver/node.rb

@@ -290,11 +290,14 @@ module TreeHaver
     # Get a child by index
     #
     # @param index [Integer] Child index
-    # @return [Node, nil] Wrapped child node
+    # @return [Node, nil] Wrapped child node, or nil if index out of bounds
     def child(index)
       child_node = @inner_node.child(index)
       return if child_node.nil?
       Node.new(child_node, source: @source)
+    rescue IndexError
+      # Some backends (e.g., MRI w/ ruby_tree_sitter) raise IndexError for out of bounds
+      nil
     end
 
     # Get a named child by index