tree_haver 2.0.0 → 3.1.0

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
@@ -163,10 +165,20 @@ module TreeHaver
     def start_point
       if @inner_node.respond_to?(:start_point)
         point = @inner_node.start_point
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       elsif @inner_node.respond_to?(:start_position)
         point = @inner_node.start_position
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       else
         raise TreeHaver::Error, "Backend node does not support start_point/start_position"
       end
@@ -178,15 +190,71 @@ module TreeHaver
     def end_point
       if @inner_node.respond_to?(:end_point)
         point = @inner_node.end_point
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       elsif @inner_node.respond_to?(:end_position)
         point = @inner_node.end_position
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       else
         raise TreeHaver::Error, "Backend node does not support end_point/end_position"
       end
     end
 
+    # Get the 1-based line number where this node starts
+    #
+    # Convenience method that converts 0-based row to 1-based line number.
+    # This is useful for error messages and matching with editor line numbers.
+    #
+    # @return [Integer] 1-based line number
+    def start_line
+      start_point.row + 1
+    end
+
+    # Get the 1-based line number where this node ends
+    #
+    # Convenience method that converts 0-based row to 1-based line number.
+    #
+    # @return [Integer] 1-based line number
+    def end_line
+      end_point.row + 1
+    end
+
+    # Get position information as a hash
+    #
+    # Returns a hash with 1-based line numbers and 0-based columns.
+    # This format is compatible with *-merge gems' FileAnalysisBase.
+    #
+    # @return [Hash{Symbol => Integer}] Position hash
+    # @example
+    #   node.source_position
+    #   # => { start_line: 1, end_line: 3, start_column: 0, end_column: 10 }
+    def source_position
+      {
+        start_line: start_line,
+        end_line: end_line,
+        start_column: start_point.column,
+        end_column: end_point.column,
+      }
+    end
+
+    # Get the first child node
+    #
+    # Convenience method for iteration patterns that expect first_child.
+    #
+    # @return [Node, nil] First child node or nil if no children
+    def first_child
+      child(0)
+    end
+
     # Get the node's text content
     #
     # @return [String]
@@ -226,6 +294,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 +330,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 +484,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 if cmp.nonzero?
+
+      cmp = end_byte <=> other.end_byte
+      return cmp if cmp.nonzero?
+
+      # 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.1.0"
   end
 
   # Traditional location for VERSION constant