tree_haver 3.1.2 → 3.2.1

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,87 @@ 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)
+          return @loaded if @load_attempted
+
+          @load_attempted = true
+          @loaded = 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"
 
-          @ffi_gem_available = begin
             require "ffi"
             true
           rescue LoadError
             false
           end
         end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false
+          @loaded = false
+        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 +209,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 +232,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 +251,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 +262,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,19 +391,20 @@ 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
 
             requested = symbol || ENV["TREE_SITTER_LANG_SYMBOL"]
-            base = File.basename(path)
-            guessed_lang = base.sub(/^libtree[-_]sitter[-_]/, "").sub(/\.(so(\.\d+)?)|\.dylib|\.dll\z/, "")
+            # Use shared utility for consistent symbol derivation across backends
+            guessed_symbol = LibraryPathUtils.derive_symbol_from_path(path)
             # If an override was provided (arg or ENV), treat it as strict and do not fall back.
             # Only when no override is provided do we attempt guessed and default candidates.
             candidates = if requested && !requested.to_s.empty?
               [requested]
             else
-              [(guessed_lang.empty? ? nil : "tree_sitter_#{guessed_lang}"), "tree_sitter_toml"].compact
+              [guessed_symbol, "tree_sitter_toml"].compact.uniq
             end
 
             func = nil

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
@@ -311,9 +316,11 @@ module TreeHaver
           def from_library(path, symbol: nil, name: nil)
             raise TreeHaver::NotAvailable, "Java backend not available" unless Java.available?
 
-            # Derive symbol from name or path if not provided
-            base_name = File.basename(path, ".*").sub(/^lib/, "")
-            sym = symbol || "tree_sitter_#{name || base_name.sub(/^tree-sitter-/, "")}"
+            # Use shared utility for consistent symbol derivation across backends
+            # If symbol not provided, derive from name or path
+            sym = symbol || LibraryPathUtils.derive_symbol_from_path(path)
+            # If name was provided, use it to override the derived symbol
+            sym = "tree_sitter_#{name}" if name && !symbol
 
             begin
               arena = ::Java::JavaLangForeign::Arena.global

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
 
@@ -153,6 +166,21 @@ module TreeHaver
         #   lang = TreeHaver::Backends::MRI::Language.from_library("/path/to/lib.so", symbol: "tree_sitter_json")
         class << self
           def from_library(path, symbol: nil, name: nil)
+            # Derive symbol from path if not provided using shared utility
+            symbol ||= LibraryPathUtils.derive_symbol_from_path(path)
+            from_path(path, symbol: symbol, name: name)
+          end
+
+          private
+
+          # Load a language from a shared library path (internal implementation)
+          #
+          # @param path [String] absolute path to the language shared library
+          # @param symbol [String] the exported symbol name (e.g., "tree_sitter_json")
+          # @param name [String, nil] optional language name
+          # @return [Language] wrapped language handle
+          # @api private
+          def from_path(path, symbol: nil, name: nil)
             raise TreeHaver::NotAvailable, "ruby_tree_sitter not available" unless MRI.available?
 
             # ruby_tree_sitter's TreeSitter::Language.load takes (language_name, path_to_so)
@@ -160,8 +188,8 @@ module TreeHaver
             # NOT the full symbol name (e.g., NOT "tree_sitter_toml")
             # and path_to_so is the full path to the .so file
             #
-            # If name is not provided, derive it from symbol by stripping "tree_sitter_" prefix
-            language_name = name || symbol&.sub(/\Atree_sitter_/, "")
+            # If name is not provided, derive it from symbol using shared utility
+            language_name = name || LibraryPathUtils.derive_language_name_from_symbol(symbol)
             ts_lang = ::TreeSitter::Language.load(language_name, path)
             new(ts_lang, path: path, symbol: symbol)
           rescue NameError => e
@@ -177,16 +205,6 @@ module TreeHaver
               raise # Re-raise if it's not a TreeSitter error
             end
           end
-
-          # Load a language from a shared library path (legacy method)
-          #
-          # @param path [String] absolute path to the language shared library
-          # @param symbol [String] the exported symbol name (e.g., "tree_sitter_json")
-          # @return [Language] wrapped language handle
-          # @deprecated Use {from_library} instead
-          def from_path(path, symbol: nil)
-            from_library(path, symbol: symbol)
-          end
         end
       end
 
@@ -216,19 +234,17 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # Note: TreeHaver::Parser unwraps language objects before calling this method.
-        # This backend receives raw ::TreeSitter::Language objects, never wrapped ones.
-        #
-        # @param lang [::TreeSitter::Language] the language to use (already unwrapped)
-        # @return [::TreeSitter::Language] the language that was set
+        # @param lang [::TreeSitter::Language, TreeHaver::Backends::MRI::Language] the language to use
+        # @return [::TreeSitter::Language, TreeHaver::Backends::MRI::Language] the language that was set
         # @raise [TreeHaver::NotAvailable] if setting language fails
         def language=(lang)
-          # lang is already unwrapped by TreeHaver::Parser, use directly
-          @parser.language = lang
+          # Unwrap if it's a TreeHaver wrapper
+          inner_lang = lang.respond_to?(:inner_language) ? lang.inner_language : lang
+          @parser.language = inner_lang
           # Verify it was set
           raise TreeHaver::NotAvailable, "Language not set correctly" if @parser.language.nil?
 
-          # Return the language object
+          # Return the original language object (wrapped or unwrapped)
           lang
         rescue Exception => e # rubocop:disable Lint/RescueException
           # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+

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"
 
@@ -136,16 +149,15 @@ module TreeHaver
 
             # tree_stump uses TreeStump.register_lang(name, path) to register languages
             # The name is used to derive the symbol automatically (tree_sitter_<name>)
-            lang_name = name || File.basename(path, ".*").sub(/^libtree-sitter-/, "")
+            # Use shared utility for consistent path parsing across backends
+            lang_name = name || LibraryPathUtils.derive_language_name_from_path(path)
             ::TreeStump.register_lang(lang_name, path)
             new(lang_name, path: path)
           rescue RuntimeError => e
             raise TreeHaver::NotAvailable, "Failed to load language from #{path}: #{e.message}"
           end
 
-          # Alias for compatibility
-          #
-          # @see from_library
+          # Backward-compatible alias for from_library
           alias_method :from_path, :from_library
         end
       end

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/grammar_finder.rb

@@ -270,7 +270,10 @@ module TreeHaver
           # Try to instantiate a parser - this will fail if runtime isn't available
           mod::Parser.new
           true
-        rescue NoMethodError, FFI::NotFoundError, LoadError, NotAvailable => _e
+        rescue NoMethodError, LoadError, NotAvailable => _e
+          false
+        rescue StandardError => _e
+          # Catch FFI::NotFoundError and other errors when FFI is loaded
           false
         end
       end