tree_haver 2.0.0 → 3.0.0

data/lib/tree_haver/grammar_finder.rb

@@ -142,14 +142,37 @@ module TreeHaver
     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
+      if env_path
+        # Store why env path was rejected for better error messages
+        @env_rejection_reason = validate_env_path(env_path)
+        return env_path if @env_rejection_reason.nil?
       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.
@@ -205,15 +228,17 @@ module TreeHaver
     #
     # @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: find_library_path,
-        available: available?,
+        found_path: found,
+        available: !found.nil?,
       }
     end
 
@@ -221,9 +246,19 @@ module TreeHaver
     #
     # @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}."
+      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
+        " #{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

data/lib/tree_haver/language_registry.rb

@@ -4,86 +4,93 @@ 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
+  # 1. **Registrations**: Store mappings from language names to backend-specific configurations
   # 2. **Cache**: Memoize loaded Language objects to avoid repeated dlopen calls
   #
-  # All operations are thread-safe and protected by a mutex.
+  # The registry supports multiple backends for the same language, allowing runtime
+  # switching, benchmarking, and fallback scenarios.
   #
-  # @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
+  # Registration structure:
+  # @registrations = {
+  #   toml: {
+  #     tree_sitter: { path: "/path/to/lib.so", symbol: "tree_sitter_toml" },
+  #     citrus: { grammar_module: TomlRB::Document, gem_name: "toml-rb" }
+  #   }
+  # }
+  #
+  # @example Register tree-sitter grammar
+  #   TreeHaver::LanguageRegistry.register(:toml, :tree_sitter,
+  #     path: "/path/to/lib.so", symbol: "tree_sitter_toml")
+  #
+  # @example Register Citrus grammar
+  #   TreeHaver::LanguageRegistry.register(:toml, :citrus,
+  #     grammar_module: TomlRB::Document, gem_name: "toml-rb")
   #
   # @api private
   module LanguageRegistry
     @mutex = Mutex.new
-    @cache = {}
-    @registrations = {}
+    @cache = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+    @registrations = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
 
     module_function
 
-    # Register a language helper by name
+    # Register a language for a specific backend
     #
-    # 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}.
+    # 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 path [String] absolute path to the language shared library
-    # @param symbol [String, nil] optional exported factory symbol (e.g., "tree_sitter_toml")
+    # @param backend_type [Symbol] backend type (:tree_sitter, :citrus, :mri, :rust, :ffi, :java)
+    # @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)
     # @return [void]
-    # @example
-    #   LanguageRegistry.register(:toml, path: "/usr/local/lib/libtree-sitter-toml.so")
-    def register(name, path:, symbol: nil)
+    # @example Register tree-sitter grammar
+    #   LanguageRegistry.register(:toml, :tree_sitter,
+    #     path: "/usr/local/lib/libtree-sitter-toml.so", symbol: "tree_sitter_toml")
+    # @example Register Citrus grammar
+    #   LanguageRegistry.register(:toml, :citrus,
+    #     grammar_module: TomlRB::Document, gem_name: "toml-rb")
+    def register(name, backend_type, **config)
       key = name.to_sym
-      @mutex.synchronize do
-        @registrations[key] = {path: path, symbol: symbol}
-      end
-      nil
-    end
+      backend_key = backend_type.to_sym
 
-    # 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)
+        @registrations[key] ||= {}
+        @registrations[key][backend_key] = config.compact
       end
       nil
     end
 
-    # Fetch a registration entry
+    # Fetch registration entries for a language
     #
-    # Returns the stored path and symbol for a registered language name.
+    # Returns all backend-specific configurations for a language.
     #
     # @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
+    # @param backend_type [Symbol, nil] optional backend type to filter by
+    # @return [Hash{Symbol => Hash}, Hash, nil] all backends or specific backend config
+    # @example Get all backends
+    #   entries = LanguageRegistry.registered(:toml)
+    #   # => {
+    #   #   tree_sitter: { path: "/usr/local/lib/libtree-sitter-toml.so", symbol: "tree_sitter_toml" },
+    #   #   citrus: { grammar_module: TomlRB::Document, gem_name: "toml-rb" }
+    #   # }
+    # @example Get specific backend
+    #   entry = LanguageRegistry.registered(:toml, :citrus)
+    #   # => { grammar_module: TomlRB::Document, gem_name: "toml-rb" }
+    def registered(name, backend_type = nil)
+      @mutex.synchronize do
+        lang_config = @registrations[name.to_sym]
+        return unless lang_config
 
-    # 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
+        if backend_type
+          lang_config[backend_type.to_sym]
+        else
+          lang_config
+        end
+      end
     end
 
     # Fetch a cached language by key or compute and store it
@@ -119,21 +126,5 @@ module TreeHaver
       @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

data/lib/tree_haver/node.rb

@@ -94,6 +94,8 @@ module TreeHaver
   #
   # @note This is the key to tree_haver's "write once, run anywhere" promise
   class Node
+    include Comparable
+
     # The wrapped backend-specific node object
     #
     # This provides direct access to the underlying backend node for advanced usage
@@ -226,6 +228,26 @@ module TreeHaver
       end
     end
 
+    # Check if the node is structural (non-terminal)
+    #
+    # In tree-sitter, this is equivalent to being a "named" node.
+    # Named nodes represent actual syntactic constructs (e.g., table, keyvalue, string)
+    # while anonymous nodes are syntax/punctuation (e.g., [, =, whitespace).
+    #
+    # For Citrus backends, this checks if the node is a non-terminal rule.
+    #
+    # @return [Boolean] true if this is a structural (non-terminal) node
+    def structural?
+      # Delegate to inner_node if it has its own structural? method (e.g., Citrus)
+      if @inner_node.respond_to?(:structural?)
+        @inner_node.structural?
+      else
+        # For tree-sitter backends, named? is equivalent to structural?
+        # Named nodes are syntactic constructs; anonymous nodes are punctuation
+        named?
+      end
+    end
+
     # Get the number of children
     # @return [Integer]
     def child_count
@@ -242,6 +264,77 @@ module TreeHaver
       Node.new(child_node, source: @source)
     end
 
+    # Get a named child by index
+    #
+    # Returns the nth named child (skipping unnamed children).
+    # Uses backend's native named_child if available, otherwise provides fallback.
+    #
+    # @param index [Integer] Named child index (0-based)
+    # @return [Node, nil] Wrapped named child node, or nil if index out of bounds
+    def named_child(index)
+      # Try native implementation first
+      if @inner_node.respond_to?(:named_child)
+        child_node = @inner_node.named_child(index)
+        return if child_node.nil?
+        return Node.new(child_node, source: @source)
+      end
+
+      # Fallback: manually iterate through children and count named ones
+      named_count = 0
+      (0...child_count).each do |i|
+        child_node = @inner_node.child(i)
+        next if child_node.nil?
+
+        # Check if this child is named
+        is_named = if child_node.respond_to?(:named?)
+          child_node.named?
+        elsif child_node.respond_to?(:is_named?)
+          child_node.is_named?
+        else
+          true  # Assume named if we can't determine
+        end
+
+        if is_named
+          return Node.new(child_node, source: @source) if named_count == index
+          named_count += 1
+        end
+      end
+
+      nil  # Index out of bounds
+    end
+
+    # Get the count of named children
+    #
+    # Uses backend's native named_child_count if available, otherwise provides fallback.
+    #
+    # @return [Integer] Number of named children
+    def named_child_count
+      # Try native implementation first
+      if @inner_node.respond_to?(:named_child_count)
+        return @inner_node.named_child_count
+      end
+
+      # Fallback: count named children manually
+      count = 0
+      (0...child_count).each do |i|
+        child_node = @inner_node.child(i)
+        next if child_node.nil?
+
+        # Check if this child is named
+        is_named = if child_node.respond_to?(:named?)
+          child_node.named?
+        elsif child_node.respond_to?(:is_named?)
+          child_node.is_named?
+        else
+          true  # Assume named if we can't determine
+        end
+
+        count += 1 if is_named
+      end
+
+      count
+    end
+
     # Get all children as wrapped nodes
     #
     # @return [Array<Node>] Array of wrapped child nodes
@@ -325,6 +418,63 @@ module TreeHaver
       text
     end
 
+    # Compare nodes for ordering (used by Comparable module)
+    #
+    # Nodes are ordered by their position in the source:
+    # 1. First by start_byte (earlier nodes come first)
+    # 2. Then by end_byte for tie-breaking (shorter spans come first)
+    # 3. Then by type for deterministic ordering
+    #
+    # This allows nodes to be sorted by position and used in sorted collections.
+    # The Comparable module provides <, <=, ==, >=, >, and between? based on this.
+    #
+    # @param other [Node] node to compare with
+    # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+    def <=>(other)
+      return unless other.is_a?(Node)
+
+      # Compare by position first (start_byte, then end_byte)
+      cmp = start_byte <=> other.start_byte
+      return cmp unless cmp.zero?
+
+      cmp = end_byte <=> other.end_byte
+      return cmp unless cmp.zero?
+
+      # For nodes at the same position with same span, compare by type
+      type <=> other.type
+    end
+
+    # Check equality based on inner_node identity
+    #
+    # Two nodes are equal if they wrap the same backend node object.
+    # This is separate from the <=> comparison which orders by position.
+    # Nodes at the same position but wrapping different backend nodes are
+    # equal according to <=> (positional equality) but not equal according to == (identity equality).
+    #
+    # Note: We override Comparable's default == behavior to check inner_node identity
+    # rather than just relying on <=> returning 0, because we want identity-based
+    # equality for testing and collection membership, not position-based equality.
+    #
+    # @param other [Object] object to compare with
+    # @return [Boolean] true if both nodes wrap the same inner_node
+    def ==(other)
+      return false unless other.is_a?(Node)
+      @inner_node == other.inner_node
+    end
+
+    # Alias for == to support both styles
+    alias_method :eql?, :==
+
+    # Generate hash value for this node
+    #
+    # Uses the hash of the inner_node to ensure nodes wrapping the same
+    # backend node have the same hash value.
+    #
+    # @return [Integer] hash value
+    def hash
+      @inner_node.hash
+    end
+
     # Check if node responds to a method (includes delegation to inner_node)
     #
     # @param method_name [Symbol] method to check

data/lib/tree_haver/path_validator.rb

@@ -60,7 +60,7 @@ module TreeHaver
     # Pattern for valid symbol names (C identifier format)
     VALID_SYMBOL_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
 
-    @custom_trusted_directories = []
+    @custom_trusted_directories = [] # rubocop:disable ThreadSafety/MutableClassInstanceVariable
     @mutex = Mutex.new
 
     module_function
@@ -75,18 +75,15 @@ module TreeHaver
       @mutex.synchronize { dirs.concat(@custom_trusted_directories) }
 
       # Add directories from environment variable
-      env_dirs = ENV[TRUSTED_DIRS_ENV_VAR]
-      if env_dirs
-        env_dirs.split(",").each do |dir|
-          expanded = File.expand_path(dir.strip)
-          # :nocov:
-          # File.expand_path always returns absolute paths on Unix/macOS.
-          # This guard exists for defensive programming on exotic platforms
-          # where expand_path might behave differently, but cannot be tested
-          # in standard CI environments.
-          dirs << expanded if expanded.start_with?("/")
-          # :nocov:
-        end
+      ENV[TRUSTED_DIRS_ENV_VAR]&.split(",")&.each do |dir|
+        expanded = File.expand_path(dir.strip)
+        # :nocov:
+        # File.expand_path always returns absolute paths on Unix/macOS.
+        # This guard exists for defensive programming on exotic platforms
+        # where expand_path might behave differently, but cannot be tested
+        # in standard CI environments.
+        dirs << expanded if expanded.start_with?("/")
+        # :nocov:
       end
 
       dirs.uniq
@@ -212,21 +209,29 @@ module TreeHaver
       return false if path.nil?
 
       # Resolve the real path to handle symlinks
-      check_path = begin
-        File.realpath(path)
-      rescue Errno::ENOENT
-        # File doesn't exist yet, check the directory
-        dir = File.dirname(path)
-        begin
-          File.realpath(dir)
-        rescue Errno::ENOENT
-          return false
-        end
-      end
+      check_path = resolve_check_path(path)
+      return false if check_path.nil?
 
       trusted_directories.any? { |trusted| check_path.start_with?(trusted) }
     end
 
+    # Resolve a path to its real path for trust checking
+    #
+    # @param path [String] the path to resolve
+    # @return [String, nil] the resolved path or nil if unresolvable
+    # @api private
+    def resolve_check_path(path)
+      File.realpath(path)
+    rescue Errno::ENOENT
+      # File doesn't exist yet, check the directory
+      dir = File.dirname(path)
+      begin
+        File.realpath(dir)
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+
     # Validate a language name is safe
     #
     # Language names are used to construct:

data/lib/tree_haver/tree.rb

@@ -6,6 +6,26 @@ module TreeHaver
   # This class wraps backend-specific tree objects and provides a unified interface.
   # It stores the source text to enable text extraction from nodes.
   #
+  # == Wrapping/Unwrapping Contract
+  #
+  # TreeHaver follows a consistent pattern for object wrapping:
+  #
+  # 1. **TreeHaver::Parser** (top level) handles ALL wrapping/unwrapping
+  # 2. **Backends** work exclusively with raw backend objects
+  # 3. **User-facing API** uses only TreeHaver wrapper classes
+  #
+  # Specifically for trees:
+  # - Backend Parser#parse returns raw backend tree (TreeSitter::Tree, TreeStump::Tree, etc.)
+  # - TreeHaver::Parser#parse wraps it in TreeHaver::Tree
+  # - TreeHaver::Parser#parse_string unwraps old_tree before passing to backend
+  # - Backend Parser#parse_string receives raw backend tree, returns raw backend tree
+  # - TreeHaver::Parser#parse_string wraps the returned tree
+  #
+  # This ensures:
+  # - Backends are simple and consistent
+  # - All complexity is in one place (TreeHaver top level)
+  # - Users always work with TreeHaver wrapper classes
+  #
   # @example Basic usage
   #   parser = TreeHaver::Parser.new
   #   parser.language = TreeHaver::Language.toml
@@ -107,14 +127,30 @@ module TreeHaver
     #   # Re-parse with the edited tree for incremental parsing
     #   new_tree = parser.parse_string(tree, "x = 42")
     def edit(start_byte:, old_end_byte:, new_end_byte:, start_point:, old_end_point:, new_end_point:)
-      @inner_tree.edit(
-        start_byte: start_byte,
-        old_end_byte: old_end_byte,
-        new_end_byte: new_end_byte,
-        start_point: start_point,
-        old_end_point: old_end_point,
-        new_end_point: new_end_point,
-      )
+      # MRI backend (ruby_tree_sitter) requires an InputEdit object
+      if defined?(::TreeSitter::InputEdit) && @inner_tree.is_a?(::TreeSitter::Tree)
+        input_edit = ::TreeSitter::InputEdit.new
+        input_edit.start_byte = start_byte
+        input_edit.old_end_byte = old_end_byte
+        input_edit.new_end_byte = new_end_byte
+
+        # Convert hash points to Point objects if needed
+        input_edit.start_point = make_point(start_point)
+        input_edit.old_end_point = make_point(old_end_point)
+        input_edit.new_end_point = make_point(new_end_point)
+
+        @inner_tree.edit(input_edit)
+      else
+        # Other backends may accept keyword arguments directly
+        @inner_tree.edit(
+          start_byte: start_byte,
+          old_end_byte: old_end_byte,
+          new_end_byte: new_end_byte,
+          start_point: start_point,
+          old_end_point: old_end_point,
+          new_end_point: new_end_point,
+        )
+      end
     rescue NoMethodError => e
       # Re-raise as NotAvailable if it's about the edit method
       raise unless e.name == :edit || e.message.include?("edit")
@@ -123,6 +159,23 @@ module TreeHaver
           "Use MRI (ruby_tree_sitter), Rust (tree_stump), or Java (java-tree-sitter) backend."
     end
 
+    private
+
+    # Convert a point hash to a TreeSitter::Point if available
+    # @api private
+    def make_point(point_hash)
+      if defined?(::TreeSitter::Point)
+        pt = ::TreeSitter::Point.new
+        pt.row = point_hash[:row]
+        pt.column = point_hash[:column]
+        pt
+      else
+        point_hash
+      end
+    end
+
+    public
+
     # Check if the current backend supports incremental parsing
     #
     # Incremental parsing allows tree-sitter to reuse unchanged nodes when
@@ -151,7 +204,8 @@ module TreeHaver
     # String representation
     # @return [String]
     def inspect
-      "#<#{self.class} source_length=#{@source&.bytesize || "unknown"}>"
+      inner_class = @inner_tree ? @inner_tree.class.name : "nil"
+      "#<#{self.class} source_length=#{@source&.bytesize || "unknown"} inner_tree=#{inner_class}>"
     end
 
     # Check if tree responds to a method (includes delegation to inner_tree)

data/lib/tree_haver/version.rb

@@ -9,8 +9,8 @@ module TreeHaver
   module Version
     # Current version of the tree_haver gem
     #
-    # @return [String] the version string (e.g., "2.0.0")
-    VERSION = "2.0.0"
+    # @return [String] the version string (e.g., "3.0.0")
+    VERSION = "3.0.0"
   end
 
   # Traditional location for VERSION constant