tree_haver 3.2.2 → 3.2.4

data/lib/tree_haver/backends/java.rb

@@ -2,26 +2,35 @@
 
 module TreeHaver
   module Backends
-    # Java backend for JRuby using java-tree-sitter (jtreesitter)
+    # Java backend for JRuby using jtreesitter (java-tree-sitter)
     #
-    # This backend integrates with java-tree-sitter JARs on JRuby,
+    # This backend integrates with jtreesitter JARs on JRuby,
     # leveraging JRuby's native Java integration for optimal performance.
     #
-    # java-tree-sitter provides Java bindings to tree-sitter and supports:
+    # == Features
+    #
+    # jtreesitter (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
     # - Tree editing for incremental re-parsing
     #
+    # == Version Requirements
+    #
+    # - jtreesitter >= 0.26.0 (required)
+    # - tree-sitter runtime library >= 0.26.0 (must match jtreesitter version)
+    #
+    # Older versions of jtreesitter are NOT supported due to API changes.
+    #
     # == 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)
+    # - TruffleRuby: ✗ Not available (jtreesitter requires JRuby's Java interop)
     #
     # == Installation
     #
-    # 1. Download the JAR from Maven Central:
+    # 1. Download jtreesitter 0.26.0+ JAR from Maven Central:
     #    https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter
     #
     # 2. Set the environment variable to point to the JAR directory:
@@ -31,7 +40,7 @@ module TreeHaver
     #    jruby -e "require 'tree_haver'; puts TreeHaver::Backends::Java.available?"
     #
     # @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://tree-sitter.github.io/java-tree-sitter jtreesitter documentation
     # @see https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter Maven Central
     module Java
       # The Java package for java-tree-sitter
@@ -402,16 +411,49 @@ module TreeHaver
           def load_by_name(name)
             raise TreeHaver::NotAvailable, "Java backend not available" unless Java.available?
 
+            # Try to find the grammar library in standard locations
+            # Look for library names like "tree-sitter-toml" or "libtree-sitter-toml"
+            lib_names = [
+              "tree-sitter-#{name}",
+              "libtree-sitter-#{name}",
+              "tree_sitter_#{name}",
+            ]
+
             begin
-              # 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, symbol: "tree_sitter_#{name}")
+              arena = ::Java::JavaLangForeign::Arena.global
+              symbol_lookup_class = ::Java::JavaLangForeign::SymbolLookup
+
+              # Ensure runtime lookup is available
+              unless Java.runtime_lookup
+                Java.runtime_lookup = symbol_lookup_class.libraryLookup("libtree-sitter.so", arena)
+              end
+
+              # Try each library name
+              grammar_lookup = nil
+              lib_names.each do |lib_name|
+                grammar_lookup = symbol_lookup_class.libraryLookup(lib_name, arena)
+                break
+              rescue ::Java::JavaLang::IllegalArgumentException
+                # Library not found in search path, try next name
+                next
+              end
+
+              unless grammar_lookup
+                raise TreeHaver::NotAvailable,
+                  "Failed to load language '#{name}': Library not found. " \
+                    "Ensure the grammar library (e.g., libtree-sitter-#{name}.so) " \
+                    "is in LD_LIBRARY_PATH."
+              end
+
+              combined_lookup = grammar_lookup.or(Java.runtime_lookup)
+              sym = "tree_sitter_#{name}"
+              java_lang = Java.java_classes[:Language].load(combined_lookup, sym)
+              new(java_lang, symbol: sym)
             rescue ::Java::JavaLang::RuntimeException => e
               raise TreeHaver::NotAvailable,
                 "Failed to load language '#{name}': #{e.message}. " \
-                  "Ensure the grammar JAR (e.g., tree-sitter-#{name}-X.Y.Z.jar) " \
-                  "is in TREE_SITTER_JAVA_JARS_DIR."
+                  "Ensure the grammar library (e.g., libtree-sitter-#{name}.so) " \
+                  "is in LD_LIBRARY_PATH."
             end
           end
         end
@@ -450,8 +492,10 @@ module TreeHaver
         # @param source [String] the source code to parse
         # @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
+          java_result = @parser.parse(source)
+          # jtreesitter 0.26.0 returns Optional<Tree>
+          java_tree = unwrap_optional(java_result)
+          raise TreeHaver::Error, "Parser returned no tree" unless java_tree
           Tree.new(java_tree)
         end
 
@@ -466,18 +510,44 @@ module TreeHaver
         # @param old_tree [Tree, nil] previous backend tree for incremental parsing (already unwrapped)
         # @param source [String] the source code to parse
         # @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)
+        # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Parser.html#parse(java.lang.String,io.github.treesitter.jtreesitter.Tree)
         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)
+            # Get the actual Java Tree object
+            java_old_tree = if old_tree.is_a?(Tree)
+              old_tree.impl
+            else
+              unwrap_optional(old_tree)
+            end
+
+            java_result = if java_old_tree
+              # jtreesitter 0.26.0 API: parse(String source, Tree oldTree)
+              @parser.parse(source, java_old_tree)
+            else
+              @parser.parse(source)
+            end
           else
-            java_tree = @parser.parse(source)
+            java_result = @parser.parse(source)
           end
-          # Return raw Java::Tree - TreeHaver::Parser will wrap it
+          # jtreesitter 0.26.0 returns Optional<Tree>
+          java_tree = unwrap_optional(java_result)
+          raise TreeHaver::Error, "Parser returned no tree" unless java_tree
           Tree.new(java_tree)
         end
+
+        private
+
+        # Unwrap Java Optional
+        #
+        # jtreesitter 0.26.0 returns Optional<T> from many methods.
+        #
+        # @param value [Object] an Optional or direct value
+        # @return [Object, nil] unwrapped value or nil if empty
+        def unwrap_optional(value)
+          return value unless value.respond_to?(:isPresent)
+          value.isPresent ? value.get : nil
+        end
       end
 
       # Wrapper for java-tree-sitter Tree
@@ -494,8 +564,18 @@ module TreeHaver
         # Get the root node of the tree
         #
         # @return [Node] the root node
+        # @raise [TreeHaver::Error] if tree has no root node
         def root_node
-          Node.new(@impl.rootNode)
+          result = @impl.rootNode
+          # jtreesitter 0.26.0: rootNode() may return Optional<Node> or Node directly
+          java_node = if result.respond_to?(:isPresent)
+            raise TreeHaver::Error, "Tree has no root node" unless result.isPresent
+            result.get
+          else
+            result
+          end
+          raise TreeHaver::Error, "Tree has no root node" unless java_node
+          Node.new(java_node)
         end
 
         # Mark the tree as edited for incremental re-parsing
@@ -556,9 +636,27 @@ module TreeHaver
         # Get a child by index
         #
         # @param index [Integer] the child index
-        # @return [Node] the child node
+        # @return [Node, nil] the child node or nil if index out of bounds
         def child(index)
-          Node.new(@impl.child(index))
+          # jtreesitter 0.26.0: getChild returns Optional<Node> or throws IndexOutOfBoundsException
+          result = @impl.getChild(index)
+          return unless result.respond_to?(:isPresent) ? result.isPresent : result
+          java_node = result.respond_to?(:get) ? result.get : result
+          Node.new(java_node)
+        rescue ::Java::JavaLang::IndexOutOfBoundsException
+          nil
+        end
+
+        # Get a child by field name
+        #
+        # @param name [String] the field name
+        # @return [Node, nil] the child node or nil if not found
+        def child_by_field_name(name)
+          # jtreesitter 0.26.0: getChildByFieldName returns Optional<Node>
+          result = @impl.getChildByFieldName(name)
+          return unless result.respond_to?(:isPresent) ? result.isPresent : result
+          java_node = result.respond_to?(:get) ? result.get : result
+          Node.new(java_node)
         end
 
         # Iterate over children
@@ -616,6 +714,46 @@ module TreeHaver
           @impl.isMissing
         end
 
+        # Check if this is a named node
+        #
+        # @return [Boolean] true if this is a named node
+        def named?
+          @impl.isNamed
+        end
+
+        # Get the parent node
+        #
+        # @return [Node, nil] the parent node or nil if this is the root
+        def parent
+          # jtreesitter 0.26.0: getParent returns Optional<Node>
+          result = @impl.getParent
+          return unless result.respond_to?(:isPresent) ? result.isPresent : result
+          java_node = result.respond_to?(:get) ? result.get : result
+          Node.new(java_node)
+        end
+
+        # Get the next sibling node
+        #
+        # @return [Node, nil] the next sibling or nil if none
+        def next_sibling
+          # jtreesitter 0.26.0: getNextSibling returns Optional<Node>
+          result = @impl.getNextSibling
+          return unless result.respond_to?(:isPresent) ? result.isPresent : result
+          java_node = result.respond_to?(:get) ? result.get : result
+          Node.new(java_node)
+        end
+
+        # Get the previous sibling node
+        #
+        # @return [Node, nil] the previous sibling or nil if none
+        def prev_sibling
+          # jtreesitter 0.26.0: getPrevSibling returns Optional<Node>
+          result = @impl.getPrevSibling
+          return unless result.respond_to?(:isPresent) ? result.isPresent : result
+          java_node = result.respond_to?(:get) ? result.get : result
+          Node.new(java_node)
+        end
+
         # Get the text of this node
         #
         # @return [String] the source text

data/lib/tree_haver/backends/markly.rb

@@ -117,6 +117,30 @@ module TreeHaver
           def markdown(flags: nil, extensions: [:table])
             new(:markdown, flags: flags, extensions: extensions)
           end
+
+          # Load language from library path (API compatibility)
+          #
+          # Markly only supports Markdown, so path and symbol parameters are ignored.
+          # This method exists for API consistency with tree-sitter backends,
+          # allowing `TreeHaver.parser_for(:markdown)` to work regardless of backend.
+          #
+          # @param _path [String] Ignored - Markly doesn't load external grammars
+          # @param symbol [String, nil] Ignored
+          # @param name [String, nil] Language name hint (defaults to :markdown)
+          # @return [Language] Markdown language
+          # @raise [TreeHaver::NotAvailable] if requested language is not Markdown
+          def from_library(_path = nil, symbol: nil, name: nil)
+            # Derive language name from symbol if provided
+            lang_name = name || symbol&.to_s&.sub(/^tree_sitter_/, "")&.to_sym || :markdown
+
+            unless lang_name == :markdown
+              raise TreeHaver::NotAvailable,
+                "Markly backend only supports Markdown, not #{lang_name}. " \
+                  "Use a tree-sitter backend for #{lang_name} support."
+            end
+
+            markdown
+          end
         end
 
         # Comparison for sorting/equality

data/lib/tree_haver/backends/prism.rb

@@ -93,6 +93,7 @@ module TreeHaver
         # The language name (always :ruby for Prism)
         # @return [Symbol]
         attr_reader :name
+        alias_method :language_name, :name
 
         # The backend this language is for
         # @return [Symbol]
@@ -153,16 +154,28 @@ module TreeHaver
             new(:ruby, options: options)
           end
 
-          # Not applicable for Prism (tree-sitter-specific)
+          # Load language from library path (API compatibility)
           #
-          # Prism is Ruby-only and doesn't load external grammar libraries.
-          # This method exists for API compatibility but will raise an error.
+          # Prism only supports Ruby, so path and symbol parameters are ignored.
+          # This method exists for API consistency with tree-sitter backends,
+          # allowing `TreeHaver.parser_for(:ruby)` to work regardless of backend.
           #
-          # @raise [TreeHaver::NotAvailable] always raises
-          def from_library(path, symbol: nil, name: nil)
-            raise TreeHaver::NotAvailable,
-              "Prism backend doesn't use shared libraries. " \
-                "Use Prism::Language.ruby instead."
+          # @param _path [String] Ignored - Prism doesn't load external grammars
+          # @param symbol [String, nil] Ignored
+          # @param name [String, nil] Language name hint (defaults to :ruby)
+          # @return [Language] Ruby language
+          # @raise [TreeHaver::NotAvailable] if requested language is not Ruby
+          def from_library(_path = nil, symbol: nil, name: nil)
+            # Derive language name from symbol if provided
+            lang_name = name || symbol&.to_s&.sub(/^tree_sitter_/, "")&.to_sym || :ruby
+
+            unless lang_name == :ruby
+              raise TreeHaver::NotAvailable,
+                "Prism backend only supports Ruby, not #{lang_name}. " \
+                  "Use a tree-sitter backend for #{lang_name} support."
+            end
+
+            ruby
           end
 
           alias_method :from_path, :from_library

data/lib/tree_haver/backends/psych.rb

@@ -100,6 +100,30 @@ module TreeHaver
           def yaml
             new(:yaml)
           end
+
+          # Load language from library path (API compatibility)
+          #
+          # Psych only supports YAML, so path and symbol parameters are ignored.
+          # This method exists for API consistency with tree-sitter backends,
+          # allowing `TreeHaver.parser_for(:yaml)` to work regardless of backend.
+          #
+          # @param _path [String] Ignored - Psych doesn't load external grammars
+          # @param symbol [String, nil] Ignored
+          # @param name [String, nil] Language name hint (defaults to :yaml)
+          # @return [Language] YAML language
+          # @raise [TreeHaver::NotAvailable] if requested language is not YAML
+          def from_library(_path = nil, symbol: nil, name: nil)
+            # Derive language name from symbol if provided
+            lang_name = name || symbol&.to_s&.sub(/^tree_sitter_/, "")&.to_sym || :yaml
+
+            unless lang_name == :yaml
+              raise TreeHaver::NotAvailable,
+                "Psych backend only supports YAML, not #{lang_name}. " \
+                  "Use a tree-sitter backend for #{lang_name} support."
+            end
+
+            yaml
+          end
         end
 
         # Comparison for sorting/equality

data/lib/tree_haver/language.rb

@@ -211,10 +211,13 @@ module TreeHaver
 
         # 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])
+        # but a Citrus grammar (pure Ruby) is available.
+        # Only fall back when backend is :auto - explicit native backend requests should fail.
+        if TreeHaver.effective_backend == :auto
+          citrus_reg = all_backends[:citrus]
+          if citrus_reg && citrus_reg[:grammar_module]
+            return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+          end
         end
 
         # No appropriate registration found
@@ -237,17 +240,29 @@ module TreeHaver
       # - FFI can't find required symbols like ts_parser_new (FFI::NotFoundError)
       # - Invalid arguments were provided (ArgumentError)
       #
+      # Fallback to Citrus ONLY happens when:
+      # - The effective backend is :auto (user didn't explicitly request a native backend)
+      # - A Citrus grammar is registered for the language
+      #
+      # If the user explicitly requested a native backend (:mri, :rust, :ffi, :java),
+      # we should NOT silently fall back to Citrus - that would violate the user's intent.
+      #
       # @param error [Exception] the original error
       # @param all_backends [Hash] all registered backends for the language
-      # @return [Backends::Citrus::Language] if Citrus fallback available
-      # @raise [Exception] re-raises original error if no fallback
+      # @return [Backends::Citrus::Language] if Citrus fallback available and allowed
+      # @raise [Exception] re-raises original error if no fallback or fallback not allowed
       # @api private
       def handle_tree_sitter_load_failure(error, all_backends)
-        citrus_reg = all_backends[:citrus]
-        if citrus_reg && citrus_reg[:grammar_module]
-          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+        # Only fall back to Citrus when backend is :auto
+        # If user explicitly requested a native backend, respect that choice
+        effective = TreeHaver.effective_backend
+        if effective == :auto
+          citrus_reg = all_backends[:citrus]
+          if citrus_reg && citrus_reg[:grammar_module]
+            return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+          end
         end
-        # No Citrus fallback available, re-raise the original error
+        # No Citrus fallback allowed or available, re-raise the original error
         raise error
       end
     end

data/lib/tree_haver/language_registry.rb

@@ -10,12 +10,39 @@ module TreeHaver
   # The registry supports multiple backends for the same language, allowing runtime
   # switching, benchmarking, and fallback scenarios.
   #
+  # == Supported Backend Types
+  #
+  # The registry is extensible and supports any backend type. Common types include:
+  #
+  # - `:tree_sitter` - Native tree-sitter grammars (.so files)
+  # - `:citrus` - Citrus PEG parser grammars (pure Ruby)
+  # - `:prism` - Ruby's Prism parser (Ruby source only)
+  # - `:psych` - Ruby's Psych parser (YAML only)
+  # - `:commonmarker` - Commonmarker gem (Markdown)
+  # - `:markly` - Markly gem (Markdown/GFM)
+  # - `:rbs` - RBS gem (RBS type signatures) - registered externally by rbs-merge
+  #
+  # External gems can register their own backend types using the same API.
+  #
   # Registration structure:
   # ```ruby
   # @registrations = {
   #   toml: {
   #     tree_sitter: { path: "/path/to/lib.so", symbol: "tree_sitter_toml" },
   #     citrus: { grammar_module: TomlRB::Document, gem_name: "toml-rb" }
+  #   },
+  #   ruby: {
+  #     prism: { backend_module: TreeHaver::Backends::Prism }
+  #   },
+  #   yaml: {
+  #     psych: { backend_module: TreeHaver::Backends::Psych }
+  #   },
+  #   markdown: {
+  #     commonmarker: { backend_module: TreeHaver::Backends::Commonmarker },
+  #     markly: { backend_module: TreeHaver::Backends::Markly }
+  #   },
+  #   rbs: {
+  #     rbs: { backend_module: Rbs::Merge::Backends::RbsBackend }  # External
   #   }
   # }
   # ```
@@ -32,6 +59,13 @@ module TreeHaver
   #     grammar_module: TomlRB::Document, gem_name: "toml-rb")
   # ```
   #
+  # @example Register a pure Ruby backend (internal or external)
+  # ```ruby
+  #   TreeHaver::LanguageRegistry.register(:rbs, :rbs,
+  #     backend_module: Rbs::Merge::Backends::RbsBackend,
+  #     gem_name: "rbs")
+  # ```
+  #
   # @api private
   module LanguageRegistry
     @mutex = Mutex.new
@@ -45,13 +79,14 @@ module TreeHaver
     # Stores backend-specific configuration for a language. Multiple backends
     # can be registered for the same language without conflict.
     #
-    # @param name [Symbol, String] language identifier (e.g., :toml, :json)
-    # @param backend_type [Symbol] backend type (:tree_sitter, :citrus, :mri, :rust, :ffi, :java)
+    # @param name [Symbol, String] language identifier (e.g., :toml, :json, :ruby, :yaml, :rbs)
+    # @param backend_type [Symbol] backend type (:tree_sitter, :citrus, :prism, :psych, :commonmarker, :markly, or custom)
     # @param config [Hash] backend-specific configuration
     # @option config [String] :path tree-sitter library path (for tree-sitter backends)
     # @option config [String] :symbol exported symbol name (for tree-sitter backends)
     # @option config [Module] :grammar_module Citrus grammar module (for Citrus backend)
-    # @option config [String] :gem_name gem name for error messages (for Citrus backend)
+    # @option config [Module] :backend_module backend module with Language/Parser classes (for pure Ruby backends)
+    # @option config [String] :gem_name gem name for error messages and availability checks
     # @return [void]
     # @example Register tree-sitter grammar
     #   LanguageRegistry.register(:toml, :tree_sitter,
@@ -59,6 +94,9 @@ module TreeHaver
     # @example Register Citrus grammar
     #   LanguageRegistry.register(:toml, :citrus,
     #     grammar_module: TomlRB::Document, gem_name: "toml-rb")
+    # @example Register pure Ruby backend (external gem)
+    #   LanguageRegistry.register(:rbs, :rbs,
+    #     backend_module: Rbs::Merge::Backends::RbsBackend, gem_name: "rbs")
     def register(name, backend_type, **config)
       key = name.to_sym
       backend_key = backend_type.to_sym
@@ -132,5 +170,21 @@ module TreeHaver
       @mutex.synchronize { @cache.clear }
       nil
     end
+
+    # Clear all registrations and cache
+    #
+    # Removes all language registrations and cached Language objects.
+    # Primarily used in tests to reset state between test cases.
+    #
+    # @return [void]
+    # @example
+    #   LanguageRegistry.clear
+    def clear
+      @mutex.synchronize do
+        @registrations.clear
+        @cache.clear
+      end
+      nil
+    end
   end
 end

data/lib/tree_haver/node.rb

@@ -227,7 +227,21 @@ module TreeHaver
     # @return [String]
     def text
       if @inner_node.respond_to?(:text)
-        @inner_node.text
+        # Some backends (like TreeStump) require source as argument
+        # Check arity to determine how to call
+        arity = @inner_node.method(:text).arity
+        if arity == 0 || arity == -1
+          # No required arguments, or optional arguments only
+          @inner_node.text
+        elsif arity >= 1 && @source
+          # Has required argument(s) - pass source
+          @inner_node.text(@source)
+        elsif @source
+          # Fallback to byte extraction
+          @source[start_byte...end_byte] || ""
+        else
+          raise TreeHaver::Error, "Cannot extract text: backend requires source but none provided"
+        end
       elsif @source
         # Fallback: extract from source using byte positions
         @source[start_byte...end_byte] || ""