tree_haver 3.2.6 → 4.0.0

data/lib/tree_haver/base/language.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Base class for backend Language implementations
+    #
+    # This class defines the API contract for all language implementations.
+    # Backend-specific Language classes should inherit from this and implement
+    # the required interface.
+    #
+    # @abstract Subclasses must implement #name and #backend at minimum
+    class Language
+      include Comparable
+
+      # The language name (e.g., :markdown, :ruby, :json)
+      # @return [Symbol] Language name
+      attr_reader :name
+
+      # The backend this language is for
+      # @return [Symbol] Backend identifier (e.g., :commonmarker, :markly, :prism)
+      attr_reader :backend
+
+      # Language-specific options
+      # @return [Hash] Options hash
+      attr_reader :options
+
+      # Create a new Language instance
+      #
+      # @param name [Symbol, String] Language name
+      # @param backend [Symbol] Backend identifier
+      # @param options [Hash] Backend-specific options
+      def initialize(name, backend:, options: {})
+        @name = name.to_sym
+        @backend = backend.to_sym
+        @options = options
+      end
+
+      # Alias for name (tree-sitter compatibility)
+      alias_method :language_name, :name
+
+      # -- Shared Implementation ------------------------------------------------
+
+      # Comparison based on backend then name
+      # @param other [Object]
+      # @return [Integer, nil]
+      def <=>(other)
+        return unless other.is_a?(Language)
+        return unless other.respond_to?(:backend) && other.backend == backend
+
+        name <=> other.name
+      end
+
+      # Hash value for use in Sets/Hashes
+      # @return [Integer]
+      def hash
+        [backend, name, options.to_a.sort].hash
+      end
+
+      # Equality check for Hash keys
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+        return false unless other.is_a?(Language)
+
+        backend == other.backend && name == other.name && options == other.options
+      end
+
+      # Human-readable representation
+      # @return [String]
+      def inspect
+        opts = options.empty? ? "" : " options=#{options}"
+        class_name = self.class.name || "#{self.class.superclass.name}(anonymous)"
+        "#<#{class_name} name=#{name} backend=#{backend}#{opts}>"
+      end
+
+      # -- Class Methods --------------------------------------------------------
+
+      class << self
+        # Load a language from a library path (factory method)
+        #
+        # For pure-Ruby backends (Commonmarker, Markly, Prism, Psych), this
+        # typically ignores the path and returns the single supported language.
+        #
+        # For tree-sitter backends (MRI, Rust, FFI, Java), this loads the
+        # language from the shared library file.
+        #
+        # @param _path [String, nil] Path to shared library (optional for pure-Ruby)
+        # @param symbol [String, nil] Symbol name to load (optional)
+        # @param name [String, nil] Language name hint (optional)
+        # @return [Language] Loaded language instance
+        # @raise [NotImplementedError] If not implemented by subclass
+        def from_library(_path = nil, symbol: nil, name: nil)
+          raise NotImplementedError, "#{self}.from_library must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/tree_haver/base/node.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Base class for all backend Node implementations
+    #
+    # This class defines the API contract for Node objects across all backends.
+    # It provides shared implementation for common behaviors and documents
+    # required/optional methods that subclasses must implement.
+    #
+    # == Backend Architecture
+    #
+    # TreeHaver supports two categories of backends:
+    #
+    # === Tree-sitter Backends (MRI, Rust, FFI, Java)
+    #
+    # These backends use the native tree-sitter library (via different bindings).
+    # They return raw `::TreeSitter::Node` objects which are wrapped by
+    # `TreeHaver::Node` (which inherits from this class).
+    #
+    # - Backend Tree#root_node returns: `::TreeSitter::Node` (raw)
+    # - TreeHaver::Tree#root_node wraps it in: `TreeHaver::Node`
+    # - These backends do NOT define their own Tree/Node classes
+    #
+    # === Pure-Ruby/Plugin Backends (Citrus, Prism, Psych, Commonmarker, Markly)
+    #
+    # These backends define their own complete implementations:
+    # - `Backend::X::Node` - wraps parser-specific node objects
+    # - `Backend::X::Tree` - wraps parser-specific tree objects
+    #
+    # For consistency, these should also inherit from `Base::Node` and `Base::Tree`.
+    #
+    # @abstract Subclasses must implement #type, #start_byte, #end_byte, and #children
+    # @see TreeHaver::Node The main wrapper class that inherits from this
+    # @see TreeHaver::Backends::Citrus::Node Example of a backend-specific Node
+    class Node
+      include Comparable
+      include Enumerable
+
+      # The underlying backend-specific node object
+      # @return [Object] Backend node
+      attr_reader :inner_node
+
+      # The source text
+      # @return [String] Source code
+      attr_reader :source
+
+      # Source lines for byte offset calculations
+      # @return [Array<String>] Lines of source
+      attr_reader :lines
+
+      # Create a new Node wrapper
+      #
+      # @param node [Object] The backend-specific node object
+      # @param source [String, nil] The source code
+      # @param lines [Array<String>, nil] Pre-split lines (optional optimization)
+      def initialize(node, source: nil, lines: nil)
+        @inner_node = node
+        @source = source
+        @lines = lines || source&.lines || []
+      end
+
+      # -- Required API Methods ------------------------------------------------
+
+      # Get the node type as a string
+      # @return [String] Node type
+      def type
+        raise NotImplementedError, "#{self.class}#type must be implemented"
+      end
+
+      # Get byte offset where the node starts
+      # @return [Integer] Start byte offset
+      def start_byte
+        raise NotImplementedError, "#{self.class}#start_byte must be implemented"
+      end
+
+      # Get byte offset where the node ends
+      # @return [Integer] End byte offset
+      def end_byte
+        raise NotImplementedError, "#{self.class}#end_byte must be implemented"
+      end
+
+      # Get all children as an array
+      # @return [Array<Node>]
+      def children
+        raise NotImplementedError, "#{self.class}#children must be implemented"
+      end
+
+      # -- Derived Methods (use #children) -------------------------------------
+
+      # Get the number of child nodes
+      # @return [Integer] Number of children
+      def child_count
+        children.size
+      end
+
+      # Get a child node by index
+      # @param index [Integer] Child index
+      # @return [Node, nil] The child node or nil
+      def child(index)
+        children[index]
+      end
+
+      # Iterate over children
+      # @yield [Node] Child node
+      def each(&block)
+        return to_enum(__method__) unless block
+
+        children.each(&block)
+      end
+
+      # Retrieve the first child
+      # @return [Node, nil]
+      def first_child
+        children.first
+      end
+
+      # Retrieve the last child
+      # @return [Node, nil]
+      def last_child
+        children.last
+      end
+
+      # -- Optional API Methods (with default implementations) -----------------
+
+      # Get the parent node
+      # @return [Node, nil] Parent node or nil
+      def parent
+        nil
+      end
+
+      # Get the next sibling node
+      # @return [Node, nil] Next sibling or nil
+      def next_sibling
+        nil
+      end
+
+      # Get the previous sibling node
+      # @return [Node, nil] Previous sibling or nil
+      def prev_sibling
+        nil
+      end
+
+      # Check if this node is named (structural)
+      # @return [Boolean] true if named
+      def named?
+        true
+      end
+
+      # Alias for named?
+      alias_method :structural?, :named?
+
+      # Check if this node represents a syntax error
+      # @return [Boolean] true on error
+      def has_error?
+        false
+      end
+
+      # Check if this node was inserted for error recovery
+      # @return [Boolean] true if missing
+      def missing?
+        false
+      end
+
+      # Get the text content of this node
+      # @return [String] Node text
+      def text
+        return "" unless source
+
+        source[start_byte...end_byte] || ""
+      end
+
+      # Get a child by field name
+      # @param _name [String, Symbol] Field name
+      # @return [Node, nil] Child node or nil
+      def child_by_field_name(_name)
+        nil
+      end
+
+      # Get start position (row/col) - 0-based
+      # @return [Hash{Symbol => Integer}] {row: 0, column: 0}
+      def start_point
+        {row: 0, column: 0}
+      end
+
+      # Get end position (row/col) - 0-based
+      # @return [Hash{Symbol => Integer}] {row: 0, column: 0}
+      def end_point
+        {row: 0, column: 0}
+      end
+
+      # -- Shared Implementation -----------------------------------------------
+
+      # Comparison based on byte range
+      # @param other [Object]
+      # @return [Integer, nil]
+      def <=>(other)
+        return unless other.respond_to?(:start_byte) && other.respond_to?(:end_byte)
+
+        cmp = start_byte <=> other.start_byte
+        return cmp unless cmp == 0
+
+        end_byte <=> other.end_byte
+      end
+
+      # Get 1-based start line
+      # @return [Integer]
+      def start_line
+        sp = start_point
+        row = if sp.is_a?(Hash)
+          sp[:row]
+        else
+          (sp.respond_to?(:row) ? sp.row : 0)
+        end
+        row + 1
+      end
+
+      # Get 1-based end line
+      # @return [Integer]
+      def end_line
+        ep = end_point
+        row = if ep.is_a?(Hash)
+          ep[:row]
+        else
+          (ep.respond_to?(:row) ? ep.row : 0)
+        end
+        row + 1
+      end
+
+      # Get unified source position hash
+      # @return [Hash{Symbol => Integer}]
+      def source_position
+        sp = start_point
+        ep = end_point
+
+        sp_row = if sp.is_a?(Hash)
+          sp[:row]
+        else
+          (sp.respond_to?(:row) ? sp.row : 0)
+        end
+        sp_col = if sp.is_a?(Hash)
+          sp[:column]
+        else
+          (sp.respond_to?(:column) ? sp.column : 0)
+        end
+        ep_row = if ep.is_a?(Hash)
+          ep[:row]
+        else
+          (ep.respond_to?(:row) ? ep.row : 0)
+        end
+        ep_col = if ep.is_a?(Hash)
+          ep[:column]
+        else
+          (ep.respond_to?(:column) ? ep.column : 0)
+        end
+
+        {
+          start_line: sp_row + 1,
+          end_line: ep_row + 1,
+          start_column: sp_col,
+          end_column: ep_col,
+        }
+      end
+
+      # Human-readable representation
+      # @return [String]
+      def inspect
+        class_name = self.class.name || "#{self.class.superclass&.name}(anonymous)"
+        node_type = begin
+          type
+        rescue NotImplementedError
+          "(not implemented)"
+        end
+        "#<#{class_name} type=#{node_type}>"
+      end
+
+      # String conversion returns the text content
+      # @return [String]
+      def to_s
+        text
+      end
+
+      # Equality based on type and byte range
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        return false unless other.respond_to?(:type) && other.respond_to?(:start_byte) && other.respond_to?(:end_byte)
+
+        type == other.type && start_byte == other.start_byte && end_byte == other.end_byte
+      end
+
+      protected
+
+      # Calculate byte offset from line and column
+      #
+      # @param line [Integer] 0-based line number
+      # @param column [Integer] 0-based column number
+      # @return [Integer] Byte offset
+      def calculate_byte_offset(line, column)
+        return 0 if lines.empty?
+
+        offset = 0
+        lines.each_with_index do |line_content, idx|
+          if idx < line
+            offset += line_content.bytesize
+          else
+            offset += [column, line_content.bytesize].min
+            break
+          end
+        end
+        offset
+      end
+    end
+  end
+end

data/lib/tree_haver/base/parser.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Base class for backend Parser implementations
+    # Used by wrapper backends (Commonmarker, Markly, etc.)
+    # Raw backends (MRI/Rust) do not inherit from this.
+    class Parser
+      attr_accessor :language
+
+      def initialize
+        @language = nil
+      end
+
+      def parse(source)
+        raise NotImplementedError
+      end
+
+      def parse_string(_old_tree, source)
+        parse(source)
+      end
+    end
+  end
+end

data/lib/tree_haver/base/point.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Point struct for position information (row/column)
+    #
+    # Provides a consistent interface for 0-based row/column positions.
+    # Compatible with both hash-style access and method access.
+    #
+    # @example
+    #   point = TreeHaver::Base::Point.new(5, 10)
+    #   point.row      # => 5
+    #   point.column   # => 10
+    #   point[:row]    # => 5
+    #   point[:column] # => 10
+    Point = Struct.new(:row, :column) do
+      # Hash-style access for compatibility
+      # @param key [Symbol, String] :row or :column
+      # @return [Integer, nil]
+      def [](key)
+        case key
+        when :row, "row", 0
+          row
+        when :column, "column", 1
+          column
+        end
+      end
+
+      # Convert to hash
+      # @return [Hash{Symbol => Integer}]
+      def to_h
+        {row: row, column: column}
+      end
+
+      # String representation
+      # @return [String]
+      def to_s
+        "(#{row}, #{column})"
+      end
+
+      # Human-readable representation
+      # @return [String]
+      def inspect
+        "#<TreeHaver::Base::Point row=#{row} column=#{column}>"
+      end
+    end
+  end
+end

data/lib/tree_haver/base/tree.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Base class for all backend Tree implementations
+    #
+    # This class defines the API contract for Tree objects across all backends.
+    # It provides shared implementation and documents required/optional methods.
+    #
+    # == Backend Architecture
+    #
+    # TreeHaver supports two categories of backends:
+    #
+    # === Tree-sitter Backends (MRI, Rust, FFI, Java)
+    #
+    # These backends use the native tree-sitter library (via different bindings).
+    # They return raw `::TreeSitter::Tree` objects which are wrapped by
+    # `TreeHaver::Tree` (which inherits from this class).
+    #
+    # - Backend Parser returns: `::TreeSitter::Tree` (raw)
+    # - TreeHaver::Parser wraps it in: `TreeHaver::Tree`
+    # - These backends do NOT define their own Tree/Node classes
+    #
+    # === Pure-Ruby/Plugin Backends (Citrus, Prism, Psych, Commonmarker, Markly)
+    #
+    # These backends define their own complete implementations:
+    # - `Backend::X::Tree` - wraps parser-specific tree objects
+    # - `Backend::X::Node` - wraps parser-specific node objects
+    #
+    # For consistency, these should also inherit from `Base::Tree` and `Base::Node`.
+    #
+    # @abstract Subclasses must implement #root_node
+    # @see TreeHaver::Tree The main wrapper class that inherits from this
+    # @see TreeHaver::Backends::Citrus::Tree Example of a backend-specific Tree
+    class Tree
+      # The underlying backend-specific tree object
+      # @return [Object] Backend tree
+      attr_reader :inner_tree
+
+      # The source text
+      # @return [String] The original source code
+      attr_reader :source
+
+      # Source lines for byte offset calculations
+      # @return [Array<String>] Lines of source
+      attr_reader :lines
+
+      # Create a new Tree
+      #
+      # @param inner_tree [Object] The backend-specific tree object
+      # @param source [String, nil] The source code
+      # @param lines [Array<String>, nil] Pre-split lines (optional, derived from source if not provided)
+      def initialize(inner_tree = nil, source: nil, lines: nil)
+        @inner_tree = inner_tree
+        @source = source
+        @lines = lines || source&.lines || []
+      end
+
+      # -- Required API Methods ------------------------------------------------
+
+      # Get the root node of the tree
+      # @return [Node] Root node
+      def root_node
+        raise NotImplementedError, "#{self.class}#root_node must be implemented"
+      end
+
+      # -- Optional API Methods (with defaults) --------------------------------
+
+      # Get parse errors
+      # @return [Array] Errors (empty for most pure-Ruby backends)
+      def errors
+        []
+      end
+
+      # Get parse warnings
+      # @return [Array] Warnings (empty for most pure-Ruby backends)
+      def warnings
+        []
+      end
+
+      # Get comments from the document
+      # @return [Array] Comments (empty for most pure-Ruby backends)
+      def comments
+        []
+      end
+
+      # Mark the tree as edited for incremental re-parsing
+      # @return [void]
+      def edit(
+        start_byte:,
+        old_end_byte:,
+        new_end_byte:,
+        start_point:,
+        old_end_point:,
+        new_end_point:
+      )
+        # Default implementation: no-op (incremental parsing not supported)
+        # Backends that support it should override this
+      end
+
+      # Check if this tree has syntax errors
+      # @return [Boolean]
+      def has_error?
+        root = root_node
+        return false unless root
+        return true if root.has_error?
+
+        # Deep check: traverse tree looking for error nodes
+        # Use queue-based traversal to avoid deep recursion
+        queue = [root]
+        while (node = queue.shift)
+          return true if node.has_error? || node.missing?
+
+          # Add children to queue
+          node.each { |child| queue.push(child) }
+        end
+
+        false
+      end
+
+      # Human-readable representation
+      # @return [String]
+      def inspect
+        "#<#{self.class.name}>"
+      end
+    end
+  end
+end

data/lib/tree_haver/base.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Base classes for backend implementation
+  module Base
+    autoload :Node, File.join(__dir__, "base", "node")
+    autoload :Tree, File.join(__dir__, "base", "tree")
+    autoload :Parser, File.join(__dir__, "base", "parser")
+    autoload :Language, File.join(__dir__, "base", "language")
+    autoload :Point, File.join(__dir__, "base", "point")
+  end
+end

data/lib/tree_haver/node.rb

@@ -59,10 +59,7 @@ module TreeHaver
   #   end
   #
   # @note This is the key to tree_haver's "write once, run anywhere" promise
-  class Node
-    include Comparable
-    include Enumerable
-
+  class Node < Base::Node
     # The wrapped backend-specific node object
     #
     # This provides direct access to the underlying backend node for advanced usage
@@ -83,17 +80,16 @@ module TreeHaver
     #   when /TreeSitter/
     #     # ruby_tree_sitter-specific code
     #   end
-    attr_reader :inner_node
+    # NOTE: inner_node is inherited from Base::Node
 
     # The source text for text extraction
     # @return [String]
-    attr_reader :source
+    # 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)
-      @inner_node = node
-      @source = source
+      super(node, source: source)
     end
 
     # Get the node's type/kind as a string
@@ -114,8 +110,16 @@ module TreeHaver
       end
     end
 
-    # Get the node's start byte offset
-    # @return [Integer]
+    # 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