tree_haver 3.1.2 → 3.2.1

data/lib/tree_haver/language.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Represents a language grammar for parsing source code
+  #
+  # Language is the entry point for loading and using grammars. It provides
+  # a unified interface that works across all backends (MRI, Rust, FFI, Java, Citrus).
+  #
+  # For tree-sitter backends, languages are loaded from shared library files (.so/.dylib/.dll).
+  # For pure-Ruby backends (Citrus, Prism, Psych), languages are built-in or provided by gems.
+  #
+  # == Loading Languages
+  #
+  # The primary way to load a language is via registration:
+  #
+  #   TreeHaver.register_language(:toml, path: "/path/to/libtree-sitter-toml.so")
+  #   language = TreeHaver::Language.toml
+  #
+  # For explicit loading without registration:
+  #
+  #   language = TreeHaver::Language.from_library(
+  #     "/path/to/libtree-sitter-toml.so",
+  #     symbol: "tree_sitter_toml"
+  #   )
+  #
+  # For ruby_tree_sitter compatibility:
+  #
+  #   language = TreeHaver::Language.load("toml", "/path/to/libtree-sitter-toml.so")
+  #
+  # @example Register and load a language
+  #   TreeHaver.register_language(:toml, path: "/path/to/grammar.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
+
+        # from_library only works with tree-sitter backends that support .so files
+        # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) don't support from_library
+        mod = TreeHaver.resolve_native_backend_module(backend)
+
+        if mod.nil?
+          if backend
+            raise NotAvailable, "Requested backend #{backend.inspect} is not available or does not support shared libraries"
+          else
+            raise NotAvailable,
+              "No native tree-sitter backend is available for loading shared libraries. " \
+                "Available native backends (MRI, Rust, FFI, Java) require platform-specific setup. " \
+                "For pure-Ruby parsing, use backend-specific Language classes directly (e.g., Prism, Psych, Citrus)."
+          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 => e
+            # Tree-sitter failed to load - check for Citrus fallback
+            handle_tree_sitter_load_failure(e, all_backends)
+          rescue => e
+            # Also catch FFI::NotFoundError if FFI is loaded (can't reference directly as FFI may not exist)
+            if defined?(::FFI::NotFoundError) && e.is_a?(::FFI::NotFoundError)
+              handle_tree_sitter_load_failure(e, all_backends)
+            else
+              raise
+            end
+          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
+
+      private
+
+      # Handle tree-sitter load failure with optional 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)
+      #
+      # @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
+      # @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])
+        end
+        # No Citrus fallback available, re-raise the original error
+        raise error
+      end
+    end
+  end
+end

data/lib/tree_haver/library_path_utils.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Utility methods for deriving tree-sitter symbol and language names from library paths
+  #
+  # This module provides consistent path parsing across all backends that load
+  # tree-sitter grammar libraries from shared object files (.so/.dylib/.dll).
+  #
+  # @example
+  #   TreeHaver::LibraryPathUtils.derive_symbol_from_path("/usr/lib/libtree-sitter-toml.so")
+  #   # => "tree_sitter_toml"
+  #
+  #   TreeHaver::LibraryPathUtils.derive_language_name_from_path("/usr/lib/libtree-sitter-toml.so")
+  #   # => "toml"
+  module LibraryPathUtils
+    module_function
+
+    # Derive the tree-sitter symbol name from a library path
+    #
+    # Symbol names are the exported C function names (e.g., "tree_sitter_toml")
+    # that return a pointer to the TSLanguage struct.
+    #
+    # Handles various naming conventions:
+    # - libtree-sitter-toml.so → tree_sitter_toml
+    # - libtree_sitter_toml.so → tree_sitter_toml
+    # - tree-sitter-toml.so → tree_sitter_toml
+    # - tree_sitter_toml.so → tree_sitter_toml
+    # - toml.so → tree_sitter_toml (assumes simple language name)
+    #
+    # @param path [String, nil] path like "/usr/lib/libtree-sitter-toml.so"
+    # @return [String, nil] symbol like "tree_sitter_toml", or nil if path is nil
+    def derive_symbol_from_path(path)
+      return unless path
+
+      # Extract filename without extension: "libtree-sitter-toml" or "toml"
+      filename = File.basename(path, ".*")
+
+      # Handle multi-part extensions like .so.0.24
+      filename = filename.sub(/\.so(\.\d+)*\z/, "")
+
+      # Match patterns and normalize to tree_sitter_<lang>
+      case filename
+      when /\Alib[-_]?tree[-_]sitter[-_](.+)\z/
+        "tree_sitter_#{Regexp.last_match(1).tr("-", "_")}"
+      when /\Atree[-_]sitter[-_](.+)\z/
+        "tree_sitter_#{Regexp.last_match(1).tr("-", "_")}"
+      else
+        # Assume filename is just the language name (e.g., "toml.so" -> "tree_sitter_toml")
+        # Also strip "lib" prefix if present (e.g., "libtoml.so" -> "tree_sitter_toml")
+        lang = filename.sub(/\Alib/, "").tr("-", "_")
+        "tree_sitter_#{lang}"
+      end
+    end
+
+    # Derive the language name from a library path
+    #
+    # Language names are the short identifiers (e.g., "toml", "json", "ruby")
+    # used by some backends (like tree_stump/Rust) to register grammars.
+    #
+    # @param path [String, nil] path like "/usr/lib/libtree-sitter-toml.so"
+    # @return [String, nil] language name like "toml", or nil if path is nil
+    def derive_language_name_from_path(path)
+      symbol = derive_symbol_from_path(path)
+      return unless symbol
+
+      # Strip the "tree_sitter_" prefix to get the language name
+      symbol.sub(/\Atree_sitter_/, "")
+    end
+
+    # Derive language name from a symbol
+    #
+    # @param symbol [String, nil] symbol like "tree_sitter_toml"
+    # @return [String, nil] language name like "toml", or nil if symbol is nil
+    def derive_language_name_from_symbol(symbol)
+      return unless symbol
+
+      symbol.sub(/\Atree_sitter_/, "")
+    end
+  end
+end

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