tree_haver 1.0.0

data/lib/tree_haver/backends/rust.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Backends
+    # 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
+    # safety guarantees and includes precompiled binaries for common platforms.
+    #
+    # 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.
+    # @see https://github.com/anthropics/tree_stump tree_stump
+    module Rust
+      @load_attempted = false
+      @loaded = false
+
+      # Check if the Rust backend is available
+      #
+      # Attempts to require tree_stump on first call and caches the result.
+      #
+      # @return [Boolean] true if tree_stump is available
+      # @example
+      #   if TreeHaver::Backends::Rust.available?
+      #     puts "Rust backend is ready"
+      #   end
+      class << self
+        def available?
+          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          begin
+            require "tree_stump"
+
+            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          rescue LoadError
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          end
+          @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
+        # @example
+        #   TreeHaver::Backends::Rust.capabilities
+        #   # => { backend: :rust, query: true, bytes_field: true, incremental: true }
+        def capabilities
+          return {} unless available?
+          {
+            backend: :rust,
+            query: true,
+            bytes_field: true,
+            incremental: true,
+          }
+        end
+      end
+
+      # Wrapper for tree_stump Language
+      #
+      # Provides TreeHaver-compatible interface to tree_stump's language loading.
+      # tree_stump uses a registration-based API where languages are registered
+      # by name, then referenced by that name when setting parser language.
+      class Language
+        # The registered language name
+        # @return [String]
+        attr_reader :name
+
+        # @api private
+        # @param name [String] the registered language name
+        def initialize(name)
+          @name = name
+        end
+
+        # Load a language from a shared library path
+        #
+        # @param path [String] absolute path to the language shared library
+        # @param symbol [String, nil] the symbol name (accepted for API consistency, but tree_stump derives it from name)
+        # @param name [String, nil] logical name for the language (optional, derived from path if not provided)
+        # @return [Language] a wrapper holding the registered language name
+        # @raise [TreeHaver::NotAvailable] if tree_stump is not available
+        # @example
+        #   lang = TreeHaver::Backends::Rust::Language.from_library("/usr/local/lib/libtree-sitter-toml.so")
+        class << self
+          def from_library(path, symbol: nil, name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            raise TreeHaver::NotAvailable, "tree_stump not available" unless Rust.available?
+
+            # Validate the path exists before calling register_lang to provide a clear error
+            raise TreeHaver::NotAvailable, "Language library not found: #{path}" unless File.exist?(path)
+
+            # 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-/, "")
+            ::TreeStump.register_lang(lang_name, path)
+            new(lang_name)
+          rescue RuntimeError => e
+            raise TreeHaver::NotAvailable, "Failed to load language from #{path}: #{e.message}"
+          end
+
+          # Alias for compatibility
+          #
+          # @see from_library
+          alias_method :from_path, :from_library
+        end
+      end
+
+      # Wrapper for tree_stump Parser
+      #
+      # Provides TreeHaver-compatible interface to tree_stump's parser.
+      class Parser
+        # Create a new parser instance
+        #
+        # @raise [TreeHaver::NotAvailable] if tree_stump is not available
+        def initialize
+          raise TreeHaver::NotAvailable, "tree_stump not available" unless Rust.available?
+          @parser = ::TreeStump::Parser.new
+        end
+
+        # Set the language for this parser
+        #
+        # @param lang [Language, String] the language to use (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
+          lang_name = lang.respond_to?(:name) ? lang.name : lang.to_s
+          @parser.set_language(lang_name)
+          lang
+        end
+
+        # Parse source code
+        #
+        # @param source [String] the source code to parse
+        # @return [Object] the parsed syntax tree
+        def parse(source)
+          @parser.parse(source)
+        end
+
+        # Parse source code with optional incremental parsing
+        #
+        # @param old_tree [Object, nil] previous tree for incremental parsing
+        # @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
+          @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

data/lib/tree_haver/compat.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Compatibility shim for code that expects TreeSitter constants
+#
+# When required, this file creates a TreeSitter module that maps to TreeHaver
+# equivalents, allowing code written for ruby_tree_sitter to work with TreeHaver
+# without modification.
+#
+# This shim is safe and idempotent:
+# - If TreeSitter is already defined (real ruby_tree_sitter is loaded), this does nothing
+# - If TreeSitter is not defined, it creates aliases to TreeHaver
+#
+# @example Using the compatibility shim
+#   require "tree_haver/compat"
+#
+#   # Now code expecting TreeSitter will work
+#   parser = TreeSitter::Parser.new  # Actually creates TreeHaver::Parser
+#   tree = parser.parse(source)
+#
+# @note This is an opt-in feature. Only require this file if you need compatibility
+# @see TreeHaver The main module this aliases to
+
+unless defined?(TreeSitter)
+  # Compatibility module aliasing TreeHaver classes to TreeSitter
+  #
+  # @note Only defined if TreeSitter doesn't already exist
+  module TreeSitter; end
+
+  # @!parse
+  #   module TreeSitter
+  #     Error = TreeHaver::Error
+  #     Parser = TreeHaver::Parser
+  #     Tree = TreeHaver::Tree
+  #     Node = TreeHaver::Node
+  #     Language = TreeHaver::Language
+  #   end
+
+  TreeSitter::Error = TreeHaver::Error
+  TreeSitter::Parser = TreeHaver::Parser
+  TreeSitter::Tree = TreeHaver::Tree
+  TreeSitter::Node = TreeHaver::Node
+  TreeSitter::Language = TreeHaver::Language
+end

data/lib/tree_haver/grammar_finder.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module TreeHaver
+  # Generic utility for finding tree-sitter grammar shared libraries.
+  #
+  # GrammarFinder provides platform-aware discovery of tree-sitter grammar
+  # libraries. Given a language name, it searches common installation paths
+  # and supports environment variable overrides.
+  #
+  # This class is designed to be used by language-specific merge gems
+  # (toml-merge, json-merge, bash-merge, etc.) without requiring TreeHaver
+  # to have knowledge of each specific language.
+  #
+  # == Security Considerations
+  #
+  # Loading shared libraries is inherently dangerous as it executes arbitrary
+  # native code. GrammarFinder performs the following security validations:
+  #
+  # - Language names are validated to contain only safe characters
+  # - Paths from environment variables are validated before use
+  # - Path traversal attempts (../) are rejected
+  # - Only files with expected extensions (.so, .dylib, .dll) are accepted
+  #
+  # For additional security, use {#find_library_path_safe} which only returns
+  # paths from trusted system directories.
+  #
+  # @example Basic usage
+  #   finder = TreeHaver::GrammarFinder.new(:toml)
+  #   path = finder.find_library_path
+  #   # => "/usr/lib/libtree-sitter-toml.so"
+  #
+  # @example Check availability
+  #   finder = TreeHaver::GrammarFinder.new(:json)
+  #   if finder.available?
+  #     language = TreeHaver::Language.load(finder.language_name, finder.find_library_path)
+  #   end
+  #
+  # @example Register with TreeHaver
+  #   finder = TreeHaver::GrammarFinder.new(:bash)
+  #   finder.register! if finder.available?
+  #   # Now you can use: TreeHaver::Language.bash
+  #
+  # @example With custom search paths
+  #   finder = TreeHaver::GrammarFinder.new(:toml, extra_paths: ["/opt/custom/lib"])
+  #
+  # @example Secure mode (trusted directories only)
+  #   finder = TreeHaver::GrammarFinder.new(:toml)
+  #   path = finder.find_library_path_safe  # Only returns paths in trusted dirs
+  #
+  # @see PathValidator For details on security validations
+  class GrammarFinder
+    # Common base directories where tree-sitter libraries are installed
+    # Platform-specific extensions are appended automatically
+    BASE_SEARCH_DIRS = [
+      "/usr/lib",
+      "/usr/lib64",
+      "/usr/local/lib",
+      "/opt/homebrew/lib",
+    ].freeze
+
+    # @return [Symbol] the language identifier
+    attr_reader :language_name
+
+    # @return [Array<String>] additional search paths provided at initialization
+    attr_reader :extra_paths
+
+    # Initialize a grammar finder for a specific language
+    #
+    # @param language_name [Symbol, String] the tree-sitter language name (e.g., :toml, :json, :bash)
+    # @param extra_paths [Array<String>] additional paths to search (searched first after ENV)
+    # @param validate [Boolean] if true, validates the language name (default: true)
+    # @raise [ArgumentError] if language_name is invalid and validate is true
+    def initialize(language_name, extra_paths: [], validate: true)
+      name_str = language_name.to_s.downcase
+
+      if validate && !PathValidator.safe_language_name?(name_str)
+        raise ArgumentError, "Invalid language name: #{language_name.inspect}. " \
+          "Language names must start with a letter and contain only lowercase letters, numbers, and underscores."
+      end
+
+      @language_name = name_str.to_sym
+      @extra_paths = Array(extra_paths)
+    end
+
+    # Get the environment variable name for this language
+    #
+    # @return [String] the ENV var name (e.g., "TREE_SITTER_TOML_PATH")
+    def env_var_name
+      "TREE_SITTER_#{@language_name.to_s.upcase}_PATH"
+    end
+
+    # Get the expected symbol name exported by the grammar library
+    #
+    # @return [String] the symbol name (e.g., "tree_sitter_toml")
+    def symbol_name
+      "tree_sitter_#{@language_name}"
+    end
+
+    # Get the library filename for the current platform
+    #
+    # @return [String] the library filename (e.g., "libtree-sitter-toml.so")
+    def library_filename
+      ext = platform_extension
+      "libtree-sitter-#{@language_name}#{ext}"
+    end
+
+    # Generate the full list of search paths for this language
+    #
+    # Order: ENV override, extra_paths, then common system paths
+    #
+    # @return [Array<String>] all paths to search
+    def search_paths
+      paths = []
+
+      # Extra paths provided at initialization (searched after ENV)
+      @extra_paths.each do |dir|
+        paths << File.join(dir, library_filename)
+      end
+
+      # Common system paths with platform-appropriate extension
+      BASE_SEARCH_DIRS.each do |dir|
+        paths << File.join(dir, library_filename)
+      end
+
+      paths
+    end
+
+    # Find the grammar library path
+    #
+    # Searches in order:
+    # 1. Environment variable override (validated for safety)
+    # 2. Extra paths provided at initialization
+    # 3. Common system installation paths
+    #
+    # @note Paths from ENV are validated using {PathValidator.safe_library_path?}
+    #   to prevent path traversal and other attacks. Invalid ENV paths are ignored.
+    #
+    # @return [String, nil] the path to the library, or nil if not found
+    # @see #find_library_path_safe For stricter validation (trusted directories only)
+    def find_library_path
+      # Check environment variable first (highest priority)
+      env_path = ENV[env_var_name]
+      if env_path && PathValidator.safe_library_path?(env_path) && File.exist?(env_path)
+        return env_path
+      end
+
+      # Search all paths (these are constructed from trusted base dirs)
+      search_paths.find { |path| File.exist?(path) }
+    end
+
+    # Find the grammar library path with strict security validation
+    #
+    # This method only returns paths that are in trusted system directories.
+    # Use this when you want maximum security and don't need to support
+    # custom installation locations.
+    #
+    # @return [String, nil] the path to the library, or nil if not found
+    # @see PathValidator::TRUSTED_DIRECTORIES For the list of trusted directories
+    def find_library_path_safe
+      # Environment variable is NOT checked in safe mode - only trusted system paths
+      search_paths.find do |path|
+        File.exist?(path) && PathValidator.in_trusted_directory?(path)
+      end
+    end
+
+    # Check if the grammar library is available
+    #
+    # @return [Boolean] true if the library can be found
+    def available?
+      !find_library_path.nil?
+    end
+
+    # Check if the grammar library is available in a trusted directory
+    #
+    # @return [Boolean] true if the library can be found in a trusted directory
+    # @see #find_library_path_safe
+    def available_safe?
+      !find_library_path_safe.nil?
+    end
+
+    # Register this language with TreeHaver
+    #
+    # After registration, the language can be loaded via dynamic method
+    # (e.g., `TreeHaver::Language.toml`).
+    #
+    # @param raise_on_missing [Boolean] if true, raises when library not found
+    # @return [Boolean] true if registration succeeded
+    # @raise [NotAvailable] if library not found and raise_on_missing is true
+    def register!(raise_on_missing: false)
+      path = find_library_path
+      unless path
+        if raise_on_missing
+          raise NotAvailable, not_found_message
+        end
+        return false
+      end
+
+      TreeHaver.register_language(@language_name, path: path, symbol: symbol_name)
+      true
+    end
+
+    # Get debug information about the search
+    #
+    # @return [Hash] diagnostic information
+    def search_info
+      {
+        language: @language_name,
+        env_var: env_var_name,
+        env_value: ENV[env_var_name],
+        symbol: symbol_name,
+        library_filename: library_filename,
+        search_paths: search_paths,
+        found_path: find_library_path,
+        available: available?,
+      }
+    end
+
+    # Get a human-readable error message when library is not found
+    #
+    # @return [String] error message with installation hints
+    def not_found_message
+      "Tree-sitter #{@language_name} grammar not found. " \
+        "Searched: #{search_paths.join(", ")}. " \
+        "Install tree-sitter-#{@language_name} or set #{env_var_name}."
+    end
+
+    private
+
+    # Get the platform-appropriate shared library extension
+    #
+    # @return [String] ".so" on Linux, ".dylib" on macOS
+    def platform_extension
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/i
+        ".dylib"
+      when /mswin|mingw|cygwin/i
+        ".dll"
+      else
+        ".so"
+      end
+    end
+  end
+end

data/lib/tree_haver/language_registry.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Thread-safe language registrations and cache for loaded Language handles
+  #
+  # The LanguageRegistry provides two main functions:
+  # 1. **Registrations**: Store mappings from language names to shared library paths
+  # 2. **Cache**: Memoize loaded Language objects to avoid repeated dlopen calls
+  #
+  # All operations are thread-safe and protected by a mutex.
+  #
+  # @example Register and cache a language
+  #   TreeHaver::LanguageRegistry.register(:toml, path: "/path/to/lib.so", symbol: "tree_sitter_toml")
+  #   lang = TreeHaver::LanguageRegistry.fetch(["/path/to/lib.so", "tree_sitter_toml", "toml"]) do
+  #     # This block is called only if not cached
+  #     load_language_from_library(...)
+  #   end
+  #
+  # @api private
+  module LanguageRegistry
+    @mutex = Mutex.new
+    @cache = {}
+    @registrations = {}
+
+    module_function
+
+    # Register a language helper by name
+    #
+    # Stores a mapping from a language name to its shared library path and
+    # optional exported symbol name. After registration, the language can be
+    # accessed via dynamic helpers on {TreeHaver::Language}.
+    #
+    # @param name [Symbol, String] language identifier (e.g., :toml, :json)
+    # @param path [String] absolute path to the language shared library
+    # @param symbol [String, nil] optional exported factory symbol (e.g., "tree_sitter_toml")
+    # @return [void]
+    # @example
+    #   LanguageRegistry.register(:toml, path: "/usr/local/lib/libtree-sitter-toml.so")
+    def register(name, path:, symbol: nil)
+      key = name.to_sym
+      @mutex.synchronize do
+        @registrations[key] = {path: path, symbol: symbol}
+      end
+      nil
+    end
+
+    # Unregister a previously registered language helper
+    #
+    # Removes the registration entry but does not affect cached Language objects.
+    #
+    # @param name [Symbol, String] language identifier to unregister
+    # @return [void]
+    # @example
+    #   LanguageRegistry.unregister(:toml)
+    def unregister(name)
+      key = name.to_sym
+      @mutex.synchronize do
+        @registrations.delete(key)
+      end
+      nil
+    end
+
+    # Fetch a registration entry
+    #
+    # Returns the stored path and symbol for a registered language name.
+    #
+    # @param name [Symbol, String] language identifier
+    # @return [Hash{Symbol => String, nil}, nil] hash with :path and :symbol keys, or nil if not registered
+    # @example
+    #   entry = LanguageRegistry.registered(:toml)
+    #   # => { path: "/usr/local/lib/libtree-sitter-toml.so", symbol: "tree_sitter_toml" }
+    def registered(name)
+      @mutex.synchronize { @registrations[name.to_sym] }
+    end
+
+    # Clear all registrations
+    #
+    # Removes all registered language mappings. Primarily intended for test cleanup.
+    # Does not clear the language cache.
+    #
+    # @return [void]
+    # @example
+    #   LanguageRegistry.clear_registrations!
+    def clear_registrations!
+      @mutex.synchronize { @registrations.clear }
+      nil
+    end
+
+    # Fetch a cached language by key or compute and store it
+    #
+    # This method provides thread-safe memoization for loaded Language objects.
+    # If the key exists in the cache, the cached value is returned immediately.
+    # Otherwise, the block is called to compute the value, which is then cached.
+    #
+    # @param key [Array] cache key, typically [path, symbol, name]
+    # @yieldreturn [Object] the computed language handle (called only on cache miss)
+    # @return [Object] the cached or computed language handle
+    # @example
+    #   language = LanguageRegistry.fetch(["/path/lib.so", "symbol", "toml"]) do
+    #     expensive_language_load_operation
+    #   end
+    def fetch(key)
+      @mutex.synchronize do
+        return @cache[key] if @cache.key?(key)
+        value = yield
+        @cache[key] = value
+      end
+    end
+
+    # Clear the language cache
+    #
+    # Removes all cached Language objects. The next call to {fetch} for any key
+    # will recompute the value. Does not clear registrations.
+    #
+    # @return [void]
+    # @example
+    #   LanguageRegistry.clear_cache!
+    def clear_cache!
+      @mutex.synchronize { @cache.clear }
+      nil
+    end
+
+    # Clear everything (registrations and cache)
+    #
+    # Removes all registered languages and all cached Language objects.
+    # Useful for complete teardown in tests.
+    #
+    # @return [void]
+    # @example
+    #   LanguageRegistry.clear_all!
+    def clear_all!
+      @mutex.synchronize do
+        @registrations.clear
+        @cache.clear
+      end
+      nil
+    end
+  end
+end