tree_haver 5.0.4 → 7.0.0

data/lib/tree_haver/rspec/testable_node.rb

@@ -1,217 +0,0 @@
-# frozen_string_literal: true
-
-# Ensure TreeHaver::Node and TreeHaver::Point are loaded
-require "tree_haver"
-
-module TreeHaver
-  module RSpec
-    # A mock inner node that provides the minimal interface TreeHaver::Node expects.
-    #
-    # This is what TreeHaver::Node wraps - it simulates the backend-specific node
-    # (like tree-sitter's Node, Markly::Node, etc.)
-    #
-    # @api private
-    class MockInnerNode
-      attr_reader :type, :start_byte, :end_byte, :children_data
-
-      def initialize(
-        type:,
-        text: nil,
-        start_byte: 0,
-        end_byte: nil,
-        start_row: 0,
-        start_column: 0,
-        end_row: nil,
-        end_column: nil,
-        children: []
-      )
-        @type = type.to_s
-        @text_content = text
-        @start_byte = start_byte
-        @end_byte = end_byte || (text ? start_byte + text.length : start_byte)
-        @start_row = start_row
-        @start_column = start_column
-        @end_row = end_row || start_row
-        @end_column = end_column || (text ? start_column + text.length : start_column)
-        @children_data = children
-      end
-
-      def start_point
-        TreeHaver::Point.new(@start_row, @start_column)
-      end
-
-      def end_point
-        TreeHaver::Point.new(@end_row, @end_column)
-      end
-
-      def child_count
-        @children_data.length
-      end
-
-      def child(index)
-        return if index.nil? || index < 0 || index >= @children_data.length
-
-        @children_data[index]
-      end
-
-      # Return children array (for enumerable behavior)
-      def children
-        @children_data
-      end
-
-      def first_child
-        @children_data.first
-      end
-
-      def last_child
-        @children_data.last
-      end
-
-      # Iterate over children
-      def each(&block)
-        return enum_for(:each) unless block
-
-        @children_data.each(&block)
-      end
-
-      def named?
-        true
-      end
-
-      # Test nodes are always valid (no parse errors)
-      def has_error?
-        false
-      end
-
-      # Test nodes are never missing (not error recovery insertions)
-      def missing?
-        false
-      end
-
-      # Some backends provide text directly
-      def text
-        @text_content
-      end
-
-      # For backends that use string_content (like Markly/Commonmarker)
-      def string_content
-        @text_content
-      end
-    end
-
-    # A real TreeHaver::Node that wraps a MockInnerNode.
-    #
-    # This gives us full TreeHaver::Node behavior (#text, #type, #source_position, etc.)
-    # while allowing us to control the underlying data for testing.
-    #
-    # TestableNode is designed for testing code that works with TreeHaver nodes
-    # without requiring an actual parser backend. It creates real TreeHaver::Node
-    # instances with controlled, predictable data.
-    #
-    # @example Creating a testable node
-    #   node = TreeHaver::RSpec::TestableNode.create(
-    #     type: :heading,
-    #     text: "## My Heading",
-    #     start_line: 1
-    #   )
-    #   node.text       # => "## My Heading"
-    #   node.type       # => "heading"
-    #   node.start_line # => 1
-    #
-    # @example Creating with children
-    #   parent = TreeHaver::RSpec::TestableNode.create(
-    #     type: :document,
-    #     text: "# Title\n\nParagraph",
-    #     children: [
-    #       { type: :heading, text: "# Title", start_line: 1 },
-    #       { type: :paragraph, text: "Paragraph", start_line: 3 },
-    #     ]
-    #   )
-    #
-    # @example Using the convenience constant
-    #   # After requiring tree_haver/rspec/testable_node, you can use:
-    #   node = TestableNode.create(type: :paragraph, text: "Hello")
-    #
-    class TestableNode < TreeHaver::Node
-      class << self
-        # Create a TestableNode with the given attributes.
-        #
-        # @param type [Symbol, String] Node type (e.g., :heading, :paragraph)
-        # @param text [String] The text content of the node
-        # @param start_line [Integer] 1-based start line number (default: 1)
-        # @param end_line [Integer, nil] 1-based end line number (default: calculated from text)
-        # @param start_column [Integer] 0-based start column (default: 0)
-        # @param end_column [Integer, nil] 0-based end column (default: calculated from text)
-        # @param start_byte [Integer] Start byte offset (default: 0)
-        # @param end_byte [Integer, nil] End byte offset (default: calculated from text)
-        # @param children [Array<Hash>] Child node specifications
-        # @param source [String, nil] Full source text (default: uses text param)
-        # @return [TestableNode]
-        def create(
-          type:,
-          text: "",
-          start_line: 1,
-          end_line: nil,
-          start_column: 0,
-          end_column: nil,
-          start_byte: 0,
-          end_byte: nil,
-          children: [],
-          source: nil
-        )
-          # Convert 1-based line to 0-based row
-          start_row = start_line - 1
-          end_row = end_line ? end_line - 1 : start_row + text.count("\n")
-
-          # Calculate end_column if not provided
-          if end_column.nil?
-            lines = text.split("\n", -1)
-            end_column = lines.last&.length || 0
-          end
-
-          # Build children as MockInnerNodes
-          child_nodes = children.map do |child_spec|
-            MockInnerNode.new(**child_spec)
-          end
-
-          inner = MockInnerNode.new(
-            type: type,
-            text: text,
-            start_byte: start_byte,
-            end_byte: end_byte,
-            start_row: start_row,
-            start_column: start_column,
-            end_row: end_row,
-            end_column: end_column,
-            children: child_nodes,
-          )
-
-          # Create a real TreeHaver::Node wrapping our mock
-          # Pass source so TreeHaver::Node can extract text if needed
-          new(inner, source: source || text)
-        end
-
-        # Create multiple nodes from an array of specifications.
-        #
-        # @param specs [Array<Hash>] Array of node specifications
-        # @return [Array<TestableNode>]
-        def create_list(*specs)
-          specs.flatten.map { |spec| create(**spec) }
-        end
-      end
-
-      # Additional test helper methods
-
-      # Check if this is a testable node (for test assertions)
-      #
-      # @return [Boolean] true
-      def testable?
-        true
-      end
-    end
-  end
-end
-
-# Make TestableNode available at top level for convenience in specs.
-# This allows specs to use `TestableNode.create(...)` without the full namespace.
-TestableNode = TreeHaver::RSpec::TestableNode

data/lib/tree_haver/rspec.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# TreeHaver RSpec Integration
-#
-# This file provides RSpec helpers and configuration for testing
-# code that uses TreeHaver. Require this in your spec_helper.rb:
-#
-#   require "tree_haver/rspec"
-#
-# This will load:
-# - Dependency tags for conditional test execution
-# - TestableNode for creating mock nodes in tests
-#
-# @example spec_helper.rb
-#   require "tree_haver/rspec"
-#
-#   RSpec.configure do |config|
-#     # Your additional configuration...
-#   end
-#
-# @example Using TestableNode
-#   node = TestableNode.create(
-#     type: :heading,
-#     text: "## My Heading",
-#     start_line: 1
-#   )
-#   expect(node.type).to eq("heading")
-#
-# @see TreeHaver::RSpec::DependencyTags
-# @see TreeHaver::RSpec::TestableNode
-
-require_relative "rspec/dependency_tags"
-require_relative "rspec/testable_node"

data/lib/tree_haver/tree.rb

@@ -1,258 +0,0 @@
-# frozen_string_literal: true
-
-module TreeHaver
-  # Unified Tree wrapper providing a consistent API across all backends
-  #
-  # 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
-  #   tree = parser.parse(source)
-  #   root = tree.root_node
-  #   puts root.type
-  #
-  # @example Incremental parsing (if backend supports it)
-  #   tree = parser.parse("x = 1")
-  #   # Edit the source: "x = 1" → "x = 42"
-  #   tree.edit(
-  #     start_byte: 4,
-  #     old_end_byte: 5,
-  #     new_end_byte: 6,
-  #     start_point: { row: 0, column: 4 },
-  #     old_end_point: { row: 0, column: 5 },
-  #     new_end_point: { row: 0, column: 6 }
-  #   )
-  #   new_tree = parser.parse_string(tree, "x = 42")
-  #
-  # @example Accessing backend-specific features
-  #   # Via passthrough (method_missing delegates to inner_tree)
-  #   tree.some_backend_specific_method  # Automatically delegated
-  #
-  #   # Or explicitly via inner_tree
-  #   tree.inner_tree.some_backend_specific_method
-  class Tree < Base::Tree
-    # The wrapped backend-specific tree object
-    #
-    # This provides direct access to the underlying backend tree for advanced usage
-    # when you need backend-specific features not exposed by the unified API.
-    #
-    # @return [Object] The underlying tree (TreeSitter::Tree, TreeStump::Tree, etc.)
-    # @example Accessing backend-specific methods
-    #   # Print DOT graph (TreeStump-specific)
-    #   if tree.inner_tree.respond_to?(:print_dot_graph)
-    #     File.open("tree.dot", "w") do |f|
-    #       tree.inner_tree.print_dot_graph(f)
-    #     end
-    #   end
-    # NOTE: inner_tree is inherited from Base::Tree
-
-    # The source text
-    #
-    # Stored to enable text extraction from nodes via byte offsets.
-    #
-    # @return [String] The original source code
-    # NOTE: source is inherited from Base::Tree
-
-    # @param tree [Object] Backend-specific tree object
-    # @param source [String] Source text for node text extraction
-    def initialize(tree, source: nil)
-      super(tree, source: source)
-    end
-
-    # Get the root node of the tree
-    #
-    # @return [Node] Wrapped root node
-    def root_node
-      root = @inner_tree.root_node
-      return if root.nil?
-      Node.new(root, source: @source)
-    end
-
-    # Mark the tree as edited for incremental re-parsing
-    #
-    # Call this method after the source code has been modified but before
-    # re-parsing. This tells tree-sitter which parts of the tree are
-    # invalidated so it can efficiently re-parse only the affected regions.
-    #
-    # Not all backends support incremental parsing. Use {#supports_editing?}
-    # to check before calling this method.
-    #
-    # @param start_byte [Integer] byte offset where the edit starts
-    # @param old_end_byte [Integer] byte offset where the old text ended
-    # @param new_end_byte [Integer] byte offset where the new text ends
-    # @param start_point [Hash] starting position as `{ row:, column: }`
-    # @param old_end_point [Hash] old ending position as `{ row:, column: }`
-    # @param new_end_point [Hash] new ending position as `{ row:, column: }`
-    # @return [void]
-    # @raise [TreeHaver::NotAvailable] if the backend doesn't support incremental parsing
-    # @see https://tree-sitter.github.io/tree-sitter/using-parsers#editing
-    #
-    # @example Incremental parsing workflow
-    #   # Original source: "x = 1"
-    #   tree = parser.parse("x = 1")
-    #
-    #   # Edit the source: replace "1" with "42" at byte offset 4
-    #   tree.edit(
-    #     start_byte: 4,
-    #     old_end_byte: 5,     # "1" ends at byte 5
-    #     new_end_byte: 6,     # "42" ends at byte 6
-    #     start_point: { row: 0, column: 4 },
-    #     old_end_point: { row: 0, column: 5 },
-    #     new_end_point: { row: 0, column: 6 }
-    #   )
-    #
-    #   # 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:)
-      # 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")
-      raise TreeHaver::NotAvailable,
-        "Incremental parsing not supported by current backend. " \
-          "Use MRI (ruby_tree_sitter), Rust (tree_stump), or Java (java-tree-sitter / jtreesitter) 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
-    # re-parsing edited source code, improving performance for large files
-    # with small edits.
-    #
-    # @return [Boolean] true if {#edit} can be called on this tree
-    # @example
-    #   if tree.supports_editing?
-    #     tree.edit(...)
-    #     new_tree = parser.parse_string(tree, edited_source)
-    #   else
-    #     # Fall back to full re-parse
-    #     new_tree = parser.parse(edited_source)
-    #   end
-    def supports_editing?
-      # Try to get the edit method to verify it exists
-      # This is more reliable than respond_to? with Delegator wrappers
-      @inner_tree.method(:edit)
-      true
-    rescue NameError
-      # NameError is the parent class of NoMethodError, so this catches both
-      false
-    end
-
-    # String representation
-    # @return [String]
-    def inspect
-      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)
-    #
-    # @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_tree.respond_to?(method_name, include_private) || super
-    end
-
-    # Delegate unknown methods to the underlying backend-specific tree
-    #
-    # 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::Tree and they'll be forwarded to the
-    # underlying tree 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 tree
-    #
-    # @example Using TreeStump-specific methods
-    #   # print_dot_graph is TreeStump-specific
-    #   File.open("tree.dot", "w") do |f|
-    #     tree.print_dot_graph(f)  # Delegated to inner_tree
-    #   end
-    #
-    # @example Safe usage with respond_to? check
-    #   if tree.respond_to?(:print_dot_graph)
-    #     File.open("tree.dot", "w") { |f| tree.print_dot_graph(f) }
-    #   end
-    #
-    # @example Equivalent explicit access
-    #   tree.print_dot_graph(file)              # Via passthrough (method_missing)
-    #   tree.inner_tree.print_dot_graph(file)   # 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_tree.respond_to?(method_name)
-        @inner_tree.public_send(method_name, *args, **kwargs, &block)
-      else
-        super
-      end
-    end
-  end
-end