tree_haver 5.0.4 → 7.0.0

data/lib/tree_haver/node.rb

@@ -1,579 +0,0 @@
-# frozen_string_literal: true
-
-module TreeHaver
-  # Unified Node wrapper providing a consistent API across all backends
-  #
-  # This class wraps backend-specific node objects (TreeSitter::Node, TreeStump::Node, etc.)
-  # and provides a unified interface so code works identically regardless of which backend
-  # is being used.
-  #
-  # The wrapper automatically maps backend differences:
-  # - TreeStump uses `node.kind` → mapped to `node.type`
-  # - TreeStump uses `node.is_named?` → mapped to `node.named?`
-  # - All backends return consistent Point objects from position methods
-  #
-  # @example Basic node traversal
-  #   tree = parser.parse(source)
-  #   root = tree.root_node
-  #
-  #   puts root.type        # => "document"
-  #   puts root.start_byte  # => 0
-  #   puts root.text        # => full source text
-  #
-  #   root.children.each do |child|
-  #     puts "#{child.type} at line #{child.start_point.row + 1}"
-  #   end
-  #
-  # @example Position information
-  #   node = tree.root_node.children.first
-  #
-  #   # Point objects work as both objects and hashes
-  #   point = node.start_point
-  #   point.row              # => 0 (method access)
-  #   point[:row]            # => 0 (hash access)
-  #   point.column           # => 0
-  #
-  #   # Byte offsets
-  #   node.start_byte        # => 0
-  #   node.end_byte          # => 23
-  #
-  # @example Error detection
-  #   if node.has_error?
-  #     puts "Parse error in subtree"
-  #   end
-  #
-  #   if node.missing?
-  #     puts "This node was inserted by error recovery"
-  #   end
-  #
-  # @example Accessing backend-specific features
-  #   # Via passthrough (method_missing delegates to inner_node)
-  #   node.grammar_name  # TreeStump-specific, automatically delegated
-  #
-  #   # Or explicitly via inner_node
-  #   node.inner_node.grammar_name  # Same result
-  #
-  #   # Check if backend supports a feature
-  #   if node.inner_node.respond_to?(:some_feature)
-  #     node.some_feature
-  #   end
-  #
-  # @note This is the key to tree_haver's "write once, run anywhere" promise
-  class Node < Base::Node
-    # The wrapped backend-specific node object
-    #
-    # This provides direct access to the underlying backend node for advanced usage
-    # when you need backend-specific features not exposed by the unified API.
-    #
-    # @return [Object] The underlying node (TreeSitter::Node, TreeStump::Node, etc.)
-    # @example Accessing backend-specific methods
-    #   # TreeStump-specific: grammar information
-    #   if node.inner_node.respond_to?(:grammar_name)
-    #     puts node.inner_node.grammar_name  # => "toml"
-    #     puts node.inner_node.grammar_id    # => Integer
-    #   end
-    #
-    #   # Check backend type
-    #   case node.inner_node.class.name
-    #   when /TreeStump/
-    #     # TreeStump-specific code
-    #   when /TreeSitter/
-    #     # ruby_tree_sitter-specific code
-    #   end
-    # NOTE: inner_node is inherited from Base::Node
-
-    # The source text for text extraction
-    # @return [String]
-    # NOTE: source is inherited from Base::Node
-
-    # @param node [Object] Backend-specific node object
-    # @param source [String] Source text for text extraction
-    def initialize(node, source: nil)
-      super(node, source: source)
-    end
-
-    # Get the node's type/kind as a string
-    #
-    # Maps backend-specific methods to a unified API:
-    # - ruby_tree_sitter: node.type
-    # - tree_stump: node.kind
-    # - FFI: node.type
-    #
-    # @return [String] The node type
-    def type
-      if @inner_node.respond_to?(:type)
-        @inner_node.type.to_s
-      elsif @inner_node.respond_to?(:kind)
-        @inner_node.kind.to_s
-      else
-        raise TreeHaver::Error, "Backend node does not support type/kind"
-      end
-    end
-
-    # Alias for type (tree_stump compatibility)
-    #
-    # tree_stump uses `kind` instead of `type` for node types.
-    # This method delegates to `type` so either can be used.
-    #
-    # @return [String] The node type
-    def kind
-      type
-    end
-
-    def start_byte
-      @inner_node.start_byte
-    end
-
-    # Get the node's end byte offset
-    # @return [Integer]
-    def end_byte
-      @inner_node.end_byte
-    end
-
-    # Get the node's start position (row, column)
-    #
-    # @return [Point] with row and column accessors (also works as Hash)
-    def start_point
-      if @inner_node.respond_to?(:start_point)
-        point = @inner_node.start_point
-        # 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
-        # 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
-    end
-
-    # Get the node's end position (row, column)
-    #
-    # @return [Point] with row and column accessors (also works as Hash)
-    def end_point
-      if @inner_node.respond_to?(:end_point)
-        point = @inner_node.end_point
-        # 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
-        # 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]
-    def text
-      if @inner_node.respond_to?(:text)
-        # Some backends (like TreeStump) require source as argument
-        # Check arity to determine how to call
-        arity = @inner_node.method(:text).arity
-        if arity == 0 || arity == -1
-          # No required arguments, or optional arguments only
-          @inner_node.text
-        elsif arity >= 1 && @source
-          # Has required argument(s) - pass source
-          @inner_node.text(@source)
-        elsif @source
-          # Fallback to byte extraction
-          @source[start_byte...end_byte] || ""
-        else
-          raise TreeHaver::Error, "Cannot extract text: backend requires source but none provided"
-        end
-      elsif @source
-        # Fallback: extract from source using byte positions
-        @source[start_byte...end_byte] || ""
-      else
-        raise TreeHaver::Error, "Cannot extract text: node has no text method and no source provided"
-      end
-    end
-
-    # Check if the node has an error
-    # @return [Boolean]
-    def has_error?
-      @inner_node.has_error?
-    end
-
-    # Check if the node is missing
-    # @return [Boolean]
-    def missing?
-      @inner_node.missing?
-    end
-
-    # Check if the node is named
-    # @return [Boolean]
-    def named?
-      if @inner_node.respond_to?(:named?)
-        @inner_node.named?
-      elsif @inner_node.respond_to?(:is_named?)
-        @inner_node.is_named?
-      else
-        true # Default to true if not supported
-      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
-      @inner_node.child_count
-    end
-
-    # Get a child by index
-    #
-    # @param index [Integer] Child index
-    # @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
-    #
-    # 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
-    def children
-      (0...child_count).map { |i| child(i) }.compact
-    end
-
-    # Get named children only
-    #
-    # @return [Array<Node>] Array of named child nodes
-    def named_children
-      children.select(&:named?)
-    end
-
-    # Iterate over children
-    #
-    # @yield [Node] Each child node
-    # @return [Enumerator, nil]
-    def each(&block)
-      return to_enum(__method__) unless block_given?
-      children.each(&block)
-    end
-
-    # Get a child by field name
-    #
-    # @param name [String, Symbol] Field name
-    # @return [Node, nil] The child node for that field
-    def child_by_field_name(name)
-      if @inner_node.respond_to?(:child_by_field_name)
-        child_node = @inner_node.child_by_field_name(name.to_s)
-        return if child_node.nil?
-        Node.new(child_node, source: @source)
-      else
-        # Not all backends support field names
-        nil
-      end
-    end
-
-    # Alias for child_by_field_name
-    alias_method :field, :child_by_field_name
-
-    # Get the parent node
-    #
-    # @return [Node, nil] The parent node
-    def parent
-      return unless @inner_node.respond_to?(:parent)
-      parent_node = @inner_node.parent
-      return if parent_node.nil?
-      Node.new(parent_node, source: @source)
-    end
-
-    # Get next sibling
-    #
-    # @return [Node, nil]
-    def next_sibling
-      return unless @inner_node.respond_to?(:next_sibling)
-      sibling = @inner_node.next_sibling
-      return if sibling.nil?
-      Node.new(sibling, source: @source)
-    end
-
-    # Get previous sibling
-    #
-    # @return [Node, nil]
-    def prev_sibling
-      return unless @inner_node.respond_to?(:prev_sibling)
-      sibling = @inner_node.prev_sibling
-      return if sibling.nil?
-      Node.new(sibling, source: @source)
-    end
-
-    # String representation for debugging
-    # @return [String]
-    def inspect
-      "#<#{self.class} type=#{type} bytes=#{start_byte}..#{end_byte}>"
-    end
-
-    # String representation
-    # @return [String]
-    def to_s
-      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
-    # @param include_private [Boolean] include private methods
-    # @return [Boolean]
-    def respond_to_missing?(method_name, include_private = false)
-      @inner_node.respond_to?(method_name, include_private) || super
-    end
-
-    # Delegate unknown methods to the underlying backend-specific node
-    #
-    # This provides passthrough access for advanced usage when you need
-    # backend-specific features not exposed by TreeHaver's unified API.
-    #
-    # The delegation is automatic and transparent - you can call backend-specific
-    # methods directly on the TreeHaver::Node and they'll be forwarded to the
-    # underlying node implementation.
-    #
-    # @param method_name [Symbol] method to call
-    # @param args [Array] arguments to pass
-    # @param block [Proc] block to pass
-    # @return [Object] result from the underlying node
-    #
-    # @example Using TreeStump-specific methods
-    #   # These methods don't exist in the unified API but are in TreeStump
-    #   node.grammar_name      # => "toml" (delegated to inner_node)
-    #   node.grammar_id        # => Integer (delegated to inner_node)
-    #   node.kind_id           # => Integer (delegated to inner_node)
-    #
-    # @example Safe usage with respond_to? check
-    #   if node.respond_to?(:grammar_name)
-    #     puts "Using #{node.grammar_name} grammar"
-    #   end
-    #
-    # @example Equivalent explicit access
-    #   node.grammar_name              # Via passthrough (method_missing)
-    #   node.inner_node.grammar_name   # Explicit access (same result)
-    #
-    # @note This maintains backward compatibility with code written for
-    #   specific backends while providing the benefits of the unified API
-    def method_missing(method_name, *args, **kwargs, &block)
-      if @inner_node.respond_to?(method_name)
-        @inner_node.public_send(method_name, *args, **kwargs, &block)
-      else
-        super
-      end
-    end
-  end
-end