tree_haver 5.0.4 → 7.0.0

data/lib/tree_haver/citrus_grammar_finder.rb

@@ -1,218 +0,0 @@
-# frozen_string_literal: true
-
-module TreeHaver
-  # Utility for finding and registering Citrus grammar gems.
-  #
-  # CitrusGrammarFinder provides language-agnostic discovery of Citrus grammar
-  # gems. Given a language name and gem information, it attempts to load the
-  # grammar and register it with tree_haver.
-  #
-  # Unlike tree-sitter grammars (which are .so files), Citrus grammars are
-  # Ruby modules that respond to .parse(source). This class handles the
-  # discovery and registration of these grammars.
-  #
-  # @example Basic usage with toml-rb
-  #   finder = TreeHaver::CitrusGrammarFinder.new(
-  #     language: :toml,
-  #     gem_name: "toml-rb",
-  #     grammar_const: "TomlRB::Document"
-  #   )
-  #   finder.register! if finder.available?
-  #
-  # @example With custom require path
-  #   finder = TreeHaver::CitrusGrammarFinder.new(
-  #     language: :json,
-  #     gem_name: "json-rb",
-  #     grammar_const: "JsonRB::Grammar",
-  #     require_path: "json/rb"
-  #   )
-  #
-  # @see GrammarFinder For tree-sitter grammar discovery
-  class CitrusGrammarFinder
-    # @return [Symbol] the language identifier
-    attr_reader :language_name
-
-    # @return [String] the gem name to require
-    attr_reader :gem_name
-
-    # @return [String] the constant path to the grammar (e.g., "TomlRB::Document")
-    attr_reader :grammar_const
-
-    # @return [String, nil] custom require path (defaults to gem_name with dashes to slashes)
-    attr_reader :require_path
-
-    # Initialize a Citrus grammar finder
-    #
-    # @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 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
-      @load_attempted = false
-      @available = false
-      @grammar_module = nil
-    end
-
-    # Check if the Citrus grammar is available
-    #
-    # Attempts to require the gem and resolve the grammar constant.
-    # Result is cached after first call.
-    #
-    # @return [Boolean] true if grammar is available
-    def available?
-      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
-
-        # Try to resolve the constant
-        @grammar_module = resolve_constant(@grammar_const)
-
-        # Verify it responds to parse
-        unless @grammar_module.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
-        # :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
-        # :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
-        # :nocov: defensive - catch-all for unexpected errors
-        # Always warn about unexpected errors
-        warn("CitrusGrammarFinder: Unexpected error: #{e.class}: #{e.message}")
-        if debug
-          warn("CitrusGrammarFinder: backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
-        end
-        @available = false
-        # :nocov:
-      end
-
-      @available
-    end
-
-    # Get the resolved grammar module
-    #
-    # @return [Module, nil] the grammar module if available
-    def grammar_module
-      available? # Ensure we've tried to load
-      @grammar_module
-    end
-
-    # Register this Citrus grammar with TreeHaver
-    #
-    # After registration, the language can be used via:
-    #   TreeHaver::Language.{language_name}
-    #
-    # @param raise_on_missing [Boolean] if true, raises when grammar not available
-    # @return [Boolean] true if registration succeeded
-    # @raise [NotAvailable] if grammar not available and raise_on_missing is true
-    def register!(raise_on_missing: false)
-      unless available?
-        if raise_on_missing
-          raise NotAvailable, not_found_message
-        end
-        return false
-      end
-
-      TreeHaver.register_language(
-        @language_name,
-        grammar_module: @grammar_module,
-        gem_name: @gem_name,
-      )
-      true
-    end
-
-    # Get debug information about the search
-    #
-    # @return [Hash] diagnostic information
-    def search_info
-      {
-        language: @language_name,
-        gem_name: @gem_name,
-        grammar_const: @grammar_const,
-        require_path: @require_path,
-        available: available?,
-        grammar_module: @grammar_module&.name,
-      }
-    end
-
-    # Get a human-readable error message when grammar is not found
-    #
-    # @return [String] error message with installation hints
-    def not_found_message
-      "Citrus grammar for #{@language_name} not found. " \
-        "Install #{@gem_name} gem: gem install #{@gem_name}"
-    end
-
-    private
-
-    # Resolve a constant path like "TomlRB::Document"
-    #
-    # @param const_path [String] constant path
-    # @return [Object] the constant
-    # @raise [NameError] if constant not found
-    def resolve_constant(const_path)
-      const_path.split("::").reduce(Object) do |mod, const_name|
-        mod.const_get(const_name)
-      end
-    end
-  end
-end

data/lib/tree_haver/compat.rb

@@ -1,43 +0,0 @@
-# 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

@@ -1,374 +0,0 @@
-# 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 cause
-    #   an error to be raised (Principle of Least Surprise - explicit paths must work).
-    #
-    # @note Setting the ENV variable to an empty string explicitly disables
-    #   this grammar. This allows fallback to alternative backends (e.g., Citrus).
-    #
-    # @return [String, nil] the path to the library, or nil if not found
-    # @raise [TreeHaver::NotAvailable] if ENV variable is set to an invalid path
-    # @see #find_library_path_safe For stricter validation (trusted directories only)
-    def find_library_path
-      # Check environment variable first (highest priority)
-      # Use key? to distinguish between "not set" and "set to empty"
-      env_var = env_var_name
-      if ENV[env_var] || ENV.key?(env_var)
-        env_path = ENV[env_var]
-
-        # :nocov: defensive - ENV.key? true with nil value is rare edge case
-        if env_path.nil?
-          @env_rejection_reason = "explicitly disabled (set to nil)"
-          return
-        end
-        # :nocov:
-
-        # Empty string means "explicitly skip this grammar"
-        # This allows users to disable tree-sitter for specific languages
-        # and fall back to alternative backends like Citrus
-        if env_path.empty?
-          @env_rejection_reason = "explicitly disabled (set to empty string)"
-          return
-        end
-
-        # Store why env path was rejected for better error messages
-        @env_rejection_reason = validate_env_path(env_path)
-
-        # Principle of Least Surprise: If user explicitly sets an ENV variable
-        # to a path, that path MUST work. Don't silently fall back to auto-discovery.
-        if @env_rejection_reason
-          raise TreeHaver::NotAvailable,
-            "#{env_var_name} is set to #{env_path.inspect} but #{@env_rejection_reason}. " \
-              "Either fix the path, unset the variable to use auto-discovery, " \
-              "or set it to empty string to explicitly disable this grammar."
-        end
-
-        return env_path
-      end
-
-      # Search all paths (these are constructed from trusted base dirs)
-      search_paths.find { |path| File.exist?(path) }
-    end
-
-    # Validate an environment variable path and return reason if invalid
-    # @return [String, nil] rejection reason or nil if valid
-    def validate_env_path(path)
-      # Check for leading/trailing whitespace
-      if path != path.strip
-        return "contains leading or trailing whitespace (use #{path.strip.inspect})"
-      end
-
-      # Check if path is safe
-      unless PathValidator.safe_library_path?(path)
-        return "failed security validation (may contain path traversal or suspicious characters)"
-      end
-
-      # Check if file exists
-      unless File.exist?(path)
-        return "file does not exist"
-      end
-
-      nil # Valid!
-    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 AND usable
-    #
-    # This checks:
-    # 1. The grammar library file exists
-    # 2. The tree-sitter runtime is functional (can create a parser)
-    #
-    # This prevents registering grammars when tree-sitter isn't actually usable,
-    # allowing clean fallback to alternative backends like Citrus.
-    #
-    # @return [Boolean] true if the library can be found AND tree-sitter runtime works
-    def available?
-      path = find_library_path
-      return false if path.nil?
-
-      # Check if tree-sitter runtime is actually functional
-      # This is cached at the class level since it's the same for all grammars
-      self.class.tree_sitter_runtime_usable?
-    end
-
-    # Backends that use tree-sitter (require native runtime libraries)
-    # Other backends (Citrus, Prism, Psych, etc.) don't use tree-sitter
-    TREE_SITTER_BACKENDS = [
-      TreeHaver::Backends::MRI,
-      TreeHaver::Backends::FFI,
-      TreeHaver::Backends::Rust,
-      TreeHaver::Backends::Java,
-    ].freeze
-
-    class << self
-      # Check if the tree-sitter runtime is usable
-      #
-      # Tests whether we can actually create a tree-sitter parser.
-      # Result is cached since this is expensive and won't change during runtime.
-      #
-      # @return [Boolean] true if tree-sitter runtime is functional
-      def tree_sitter_runtime_usable?
-        return @tree_sitter_runtime_usable if defined?(@tree_sitter_runtime_usable)
-
-        @tree_sitter_runtime_usable = begin
-          # Try to create a parser using the current backend
-          mod = TreeHaver.resolve_backend_module(nil)
-
-          # Only tree-sitter backends are relevant here
-          # Non-tree-sitter backends (Citrus, Prism, Psych, etc.) don't use grammar files
-          if mod.nil? || !TREE_SITTER_BACKENDS.include?(mod)
-            false
-          else
-            # Try to instantiate a parser - this will fail if runtime isn't available
-            mod::Parser.new
-            true
-          end
-        rescue NoMethodError, LoadError, NotAvailable => _e
-          # Note: FFI::NotFoundError inherits from LoadError, so it's caught here too
-          false
-        end
-      end
-
-      # Reset the cached tree-sitter runtime check (for testing)
-      #
-      # @api private
-      def reset_runtime_check!
-        remove_instance_variable(:@tree_sitter_runtime_usable) if defined?(@tree_sitter_runtime_usable)
-      end
-    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
-      found = find_library_path # This populates @env_rejection_reason
-      {
-        language: @language_name,
-        env_var: env_var_name,
-        env_value: ENV[env_var_name],
-        env_rejection_reason: @env_rejection_reason,
-        symbol: symbol_name,
-        library_filename: library_filename,
-        search_paths: search_paths,
-        found_path: found,
-        available: !found.nil?,
-      }
-    end
-
-    # Get a human-readable error message when library is not found
-    #
-    # @return [String] error message with installation hints
-    def not_found_message
-      msg = "tree-sitter #{@language_name} grammar not found."
-
-      # Check if env var is set but rejected
-      env_value = ENV[env_var_name]
-      msg += if env_value && @env_rejection_reason
-        " #{env_var_name} is set to #{env_value.inspect} but #{@env_rejection_reason}."
-      elsif env_value && File.exist?(env_value) && !self.class.tree_sitter_runtime_usable?
-        " #{env_var_name} is set and file exists, but no tree-sitter runtime is available. " \
-          "Add ruby_tree_sitter, ffi, or tree_stump gem to your Gemfile."
-      elsif env_value
-        " #{env_var_name} is set but was not used (file may have been removed)."
-      else
-        " Searched: #{search_paths.join(", ")}."
-      end
-
-      msg + " Install tree-sitter-#{@language_name} or set #{env_var_name} to a valid path."
-    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