tree_haver 1.0.0 → 3.0.0

data/lib/tree_haver/backends/java.rb

@@ -7,7 +7,7 @@ module TreeHaver
     # This backend integrates with java-tree-sitter JARs on JRuby,
     # leveraging JRuby's native Java integration for optimal performance.
     #
-    # java-tree-sitter provides Java bindings to Tree-sitter and supports:
+    # java-tree-sitter provides Java bindings to tree-sitter and supports:
     # - Parsing source code into syntax trees
     # - Incremental parsing via Parser.parse(Tree, String)
     # - The Query API for pattern matching
@@ -228,13 +228,57 @@ module TreeHaver
       # All Java backend implementation classes require JRuby and cannot be tested on MRI/CRuby.
       # JRuby-specific CI jobs would test this code.
       class Language
+        include Comparable
+
         attr_reader :impl
 
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
+        # The symbol name (if known)
+        # @return [String, nil]
+        attr_reader :symbol
+
         # @api private
-        def initialize(impl)
+        def initialize(impl, path: nil, symbol: nil)
           @impl = impl
+          @backend = :java
+          @path = path
+          @symbol = symbol
+        end
+
+        # Compare languages for equality
+        #
+        # Java languages are equal if they have the same backend, path, and symbol.
+        # Path and symbol uniquely identify a loaded language.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          # Compare by path first, then symbol
+          cmp = (@path || "") <=> (other.path || "")
+          return cmp unless cmp.zero?
+
+          (@symbol || "") <=> (other.symbol || "")
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @path, @symbol].hash
         end
 
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
         # Load a language from a shared library
         #
         # There are three ways java-tree-sitter can load shared libraries:
@@ -298,7 +342,7 @@ module TreeHaver
               combined_lookup = grammar_lookup.or(Java.runtime_lookup)
 
               java_lang = Java.java_classes[:Language].load(combined_lookup, sym)
-              new(java_lang)
+              new(java_lang, path: path, symbol: symbol)
             rescue ::Java::JavaLang::RuntimeException => e
               cause = e.cause
               root_cause = cause&.cause || cause
@@ -354,7 +398,7 @@ module TreeHaver
               # java-tree-sitter's Language.load(String) searches for the language
               # in the classpath using standard naming conventions
               java_lang = Java.java_classes[:Language].load(name)
-              new(java_lang)
+              new(java_lang, symbol: "tree_sitter_#{name}")
             rescue ::Java::JavaLang::RuntimeException => e
               raise TreeHaver::NotAvailable,
                 "Failed to load language '#{name}': #{e.message}. " \
@@ -383,38 +427,47 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # @param lang [Language] the language to use
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # This backend receives the Language wrapper's inner impl (java Language object).
+        #
+        # @param lang [Object] the Java language object (already unwrapped)
         # @return [void]
         def language=(lang)
-          java_lang = lang.is_a?(Language) ? lang.impl : lang
-          @parser.language = java_lang
+          # lang is already unwrapped by TreeHaver::Parser
+          @parser.language = lang
         end
 
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [Tree] the parsed syntax tree
+        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         def parse(source)
           java_tree = @parser.parse(source)
+          # Return raw Java::Tree - TreeHaver::Parser will wrap it
           Tree.new(java_tree)
         end
 
         # Parse source code with optional incremental parsing
         #
+        # Note: old_tree is already unwrapped by TreeHaver::Parser before reaching this method.
+        # The backend receives the raw Tree wrapper's impl, not a TreeHaver::Tree.
+        #
         # When old_tree is provided and has been edited, tree-sitter will reuse
         # unchanged nodes for better performance.
         #
-        # @param old_tree [Tree, nil] previous tree for incremental parsing
+        # @param old_tree [Tree, nil] previous backend tree for incremental parsing (already unwrapped)
         # @param source [String] the source code to parse
-        # @return [Tree] the parsed syntax tree
+        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Parser.html#parse(io.github.treesitter.jtreesitter.Tree,java.lang.String)
         def parse_string(old_tree, source)
+          # old_tree is already unwrapped to Tree wrapper's impl by TreeHaver::Parser
           if old_tree
             java_old_tree = old_tree.is_a?(Tree) ? old_tree.impl : old_tree
             java_tree = @parser.parse(java_old_tree, source)
           else
             java_tree = @parser.parse(source)
           end
+          # Return raw Java::Tree - TreeHaver::Parser will wrap it
           Tree.new(java_tree)
         end
       end

data/lib/tree_haver/backends/mri.rb

@@ -5,7 +5,7 @@ module TreeHaver
     # MRI backend using the ruby_tree_sitter gem
     #
     # This backend wraps the ruby_tree_sitter gem, which is a native C extension
-    # for MRI Ruby. It provides the most feature-complete Tree-sitter integration
+    # 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
@@ -28,7 +28,7 @@ module TreeHaver
           return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
           @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           begin
-            require "ruby_tree_sitter"
+            require "tree_sitter" # Note: gem is ruby_tree_sitter but requires tree_sitter
 
             @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           rescue LoadError
@@ -37,6 +37,15 @@ module TreeHaver
           @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
 
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+        end
+
         # Get capabilities supported by this backend
         #
         # @return [Hash{Symbol => Object}] capability map
@@ -56,19 +65,112 @@ module TreeHaver
 
       # Wrapper for ruby_tree_sitter Language
       #
-      # This is a thin pass-through to ::TreeSitter::Language from ruby_tree_sitter.
+      # Wraps ::TreeSitter::Language from ruby_tree_sitter to provide a consistent
+      # API across all backends.
       class Language
-        # Load a language from a shared library path
+        include Comparable
+
+        # The wrapped TreeSitter::Language object
+        # @return [::TreeSitter::Language]
+        attr_reader :inner_language
+
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
+        # The symbol name (if known)
+        # @return [String, nil]
+        attr_reader :symbol
+
+        # @api private
+        # @param lang [::TreeSitter::Language] the language object from ruby_tree_sitter
+        # @param path [String, nil] path language was loaded from
+        # @param symbol [String, nil] symbol name
+        def initialize(lang, path: nil, symbol: nil)
+          @inner_language = lang
+          @backend = :mri
+          @path = path
+          @symbol = symbol
+        end
+
+        # Compare languages for equality
+        #
+        # MRI languages are equal if they have the same backend, path, and symbol.
+        # Path and symbol uniquely identify a loaded language.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          # Compare by path first, then symbol
+          cmp = (@path || "") <=> (other.path || "")
+          return cmp unless cmp.zero?
+
+          (@symbol || "") <=> (other.symbol || "")
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @path, @symbol].hash
+        end
+
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
+        # Convert to the underlying TreeSitter::Language for passing to parser
+        #
+        # @return [::TreeSitter::Language]
+        def to_language
+          @inner_language
+        end
+        alias_method :to_ts_language, :to_language
+
+        # Load a language from a shared library (preferred method)
         #
         # @param path [String] absolute path to the language shared library
-        # @return [::TreeSitter::Language] the loaded language handle
+        # @param symbol [String] the exported symbol name (e.g., "tree_sitter_json")
+        # @param name [String, nil] optional language name (unused by MRI backend)
+        # @return [Language] wrapped language handle
         # @raise [TreeHaver::NotAvailable] if ruby_tree_sitter is not available
         # @example
-        #   lang = TreeHaver::Backends::MRI::Language.from_path("/usr/local/lib/libtree-sitter-toml.so")
+        #   lang = TreeHaver::Backends::MRI::Language.from_library("/path/to/lib.so", symbol: "tree_sitter_json")
         class << self
-          def from_path(path)
+          def from_library(path, symbol: nil, name: nil)
             raise TreeHaver::NotAvailable, "ruby_tree_sitter not available" unless MRI.available?
-            ::TreeSitter::Language.load(path)
+
+            # ruby_tree_sitter's TreeSitter::Language.load takes (language_name, path_to_so)
+            # where language_name is the language identifier (e.g., "toml", "json")
+            # 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_/, "")
+            ts_lang = ::TreeSitter::Language.load(language_name, path)
+            new(ts_lang, path: path, symbol: symbol)
+          rescue NameError => e
+            # TreeSitter constant doesn't exist - backend not loaded
+            raise TreeHaver::NotAvailable, "ruby_tree_sitter not available: #{e.message}"
+          rescue TreeSitter::TreeSitterError => e
+            # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+            # This includes: ParserNotFoundError, LanguageLoadError, SymbolNotFoundError, etc.
+            raise TreeHaver::NotAvailable, "Could not load language: #{e.message}"
+          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
@@ -83,47 +185,72 @@ module TreeHaver
         def initialize
           raise TreeHaver::NotAvailable, "ruby_tree_sitter not available" unless MRI.available?
           @parser = ::TreeSitter::Parser.new
+        rescue NameError => e
+          # TreeSitter constant doesn't exist - backend not loaded
+          raise TreeHaver::NotAvailable, "ruby_tree_sitter not available: #{e.message}"
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not create parser: #{e.message}"
         end
 
         # Set the language for this parser
         #
-        # @param lang [::TreeSitter::Language] the language to use
+        # 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
+        # @raise [TreeHaver::NotAvailable] if setting language fails
         def language=(lang)
+          # lang is already unwrapped by TreeHaver::Parser, use directly
           @parser.language = lang
+          # Verify it was set
+          raise TreeHaver::NotAvailable, "Language not set correctly" if @parser.language.nil?
+
+          # Return the language object
+          lang
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not set language: #{e.message}"
         end
 
         # Parse source code
         #
+        # ruby_tree_sitter provides parse_string for string input
+        #
         # @param source [String] the source code to parse
-        # @return [::TreeSitter::Tree] the parsed syntax tree
+        # @return [::TreeSitter::Tree] raw tree (NOT wrapped - wrapping happens in TreeHaver::Parser)
+        # @raise [TreeHaver::NotAvailable] if parsing returns nil (usually means language not set)
         def parse(source)
-          @parser.parse(source)
+          # ruby_tree_sitter's parse_string(old_tree, string) method
+          # Pass nil for old_tree (initial parse)
+          # Return raw tree - TreeHaver::Parser will wrap it
+          tree = @parser.parse_string(nil, source)
+          raise TreeHaver::NotAvailable, "Parse returned nil - is language set?" if tree.nil?
+          tree
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not parse source: #{e.message}"
         end
 
         # Parse source code with optional incremental parsing
         #
-        # @param old_tree [::TreeSitter::Tree, nil] previous tree for incremental parsing
+        # Note: old_tree should already be unwrapped by TreeHaver::Parser before reaching this method.
+        # The backend receives the raw inner tree (::TreeSitter::Tree or nil), not a wrapped TreeHaver::Tree.
+        #
+        # @param old_tree [::TreeSitter::Tree, nil] previous tree for incremental parsing (already unwrapped)
         # @param source [String] the source code to parse
-        # @return [::TreeSitter::Tree] the parsed syntax tree
+        # @return [::TreeSitter::Tree] raw tree (NOT wrapped - wrapping happens in TreeHaver::Parser)
+        # @raise [TreeHaver::NotAvailable] if parsing fails
         def parse_string(old_tree, source)
+          # old_tree is already unwrapped by TreeHaver::Parser, pass it directly
+          # Return raw tree - TreeHaver::Parser will wrap it
           @parser.parse_string(old_tree, source)
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not parse source: #{e.message}"
         end
       end
-
-      # Wrapper for ruby_tree_sitter Tree
-      #
-      # Not used directly; TreeHaver passes through ::TreeSitter::Tree objects.
-      class Tree
-        # Not used directly; we pass through ruby_tree_sitter::Tree
-      end
-
-      # Wrapper for ruby_tree_sitter Node
-      #
-      # Not used directly; TreeHaver passes through ::TreeSitter::Node objects.
-      class Node
-        # Not used directly; we pass through ruby_tree_sitter::Node
-      end
     end
   end
 end

data/lib/tree_haver/backends/rust.rb

@@ -5,7 +5,7 @@ module TreeHaver
     # Rust backend using the tree_stump gem
     #
     # This backend wraps the tree_stump gem, which provides Ruby bindings to
-    # Tree-sitter written in Rust. It offers native performance with Rust's
+    # tree-sitter written in Rust. It offers native performance with Rust's
     # safety guarantees and includes precompiled binaries for common platforms.
     #
     # tree_stump supports incremental parsing and the Query API, making it
@@ -54,14 +54,14 @@ module TreeHaver
         # @return [Hash{Symbol => Object}] capability map
         # @example
         #   TreeHaver::Backends::Rust.capabilities
-        #   # => { backend: :rust, query: true, bytes_field: true, incremental: true }
+        #   # => { backend: :rust, query: true, bytes_field: true, incremental: false }
         def capabilities
           return {} unless available?
           {
             backend: :rust,
             query: true,
             bytes_field: true,
-            incremental: true,
+            incremental: false,  # TreeStump doesn't currently expose incremental parsing to Ruby
           }
         end
       end
@@ -72,16 +72,52 @@ module TreeHaver
       # tree_stump uses a registration-based API where languages are registered
       # by name, then referenced by that name when setting parser language.
       class Language
+        include Comparable
+
         # The registered language name
         # @return [String]
         attr_reader :name
 
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
         # @api private
         # @param name [String] the registered language name
-        def initialize(name)
+        # @param path [String, nil] path language was loaded from
+        def initialize(name, path: nil)
           @name = name
+          @backend = :rust
+          @path = path
         end
 
+        # Compare languages for equality
+        #
+        # Rust languages are equal if they have the same backend and name.
+        # Name uniquely identifies a registered language in TreeStump.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          @name <=> other.name
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @name].hash
+        end
+
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
         # Load a language from a shared library path
         #
         # @param path [String] absolute path to the language shared library
@@ -102,7 +138,7 @@ module TreeHaver
             # The name is used to derive the symbol automatically (tree_sitter_<name>)
             lang_name = name || File.basename(path, ".*").sub(/^libtree-sitter-/, "")
             ::TreeStump.register_lang(lang_name, path)
-            new(lang_name)
+            new(lang_name, path: path)
           rescue RuntimeError => e
             raise TreeHaver::NotAvailable, "Failed to load language from #{path}: #{e.message}"
           end
@@ -128,11 +164,16 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # @param lang [Language, String] the language to use (Language wrapper or name string)
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # When called from TreeHaver::Parser, receives String (language name).
+        # For backward compatibility and backend tests, also handles Language wrapper.
+        #
+        # @param lang [Language, String] the language wrapper or name string
         # @return [Language, String] the language that was set
         def language=(lang)
-          # tree_stump uses set_language with a string name
+          # Extract language name (handle both wrapper and raw string)
           lang_name = lang.respond_to?(:name) ? lang.name : lang.to_s
+          # tree_stump uses set_language with a string name
           @parser.set_language(lang_name)
           lang
         end
@@ -140,36 +181,26 @@ module TreeHaver
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [Object] the parsed syntax tree
+        # @return [TreeStump::Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         def parse(source)
+          # Return raw tree_stump tree - TreeHaver::Parser will wrap it
           @parser.parse(source)
         end
 
         # Parse source code with optional incremental parsing
         #
-        # @param old_tree [Object, nil] previous tree for incremental parsing
+        # Note: TreeStump does not currently expose incremental parsing to Ruby.
+        # The parse method always does a full parse, ignoring old_tree.
+        #
+        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing (ignored)
         # @param source [String] the source code to parse
-        # @return [Object] the parsed syntax tree
-        def parse_string(old_tree, source)
-          # tree_stump doesn't have parse_string, use parse instead
-          # TODO: Check if tree_stump supports incremental parsing
+        # @return [TreeStump::Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
+        def parse_string(old_tree, source) # rubocop:disable Lint/UnusedMethodArgument
+          # TreeStump's parse method only accepts source as a single argument
+          # and internally always passes None for the old tree (no incremental parsing support)
           @parser.parse(source)
         end
       end
-
-      # Wrapper for tree_stump Tree
-      #
-      # Not used directly; TreeHaver passes through tree_stump Tree objects.
-      class Tree
-        # Not used directly; we pass through tree_stump::Tree
-      end
-
-      # Wrapper for tree_stump Node
-      #
-      # Not used directly; TreeHaver passes through tree_stump::Node objects.
-      class Node
-        # Not used directly; we pass through tree_stump::Node
-      end
     end
   end
 end