tree_haver 5.0.4 → 7.0.0

data/lib/tree_haver/base/language.rb

@@ -1,98 +0,0 @@
-# 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

@@ -1,322 +0,0 @@
-# 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
-      #
-      # Returns nil for negative indices or indices out of bounds.
-      # This matches tree-sitter behavior where negative indices are invalid.
-      #
-      # @param index [Integer] Child index (0-based, non-negative)
-      # @return [Node, nil] The child node or nil
-      def child(index)
-        return if index.negative?
-        return if index >= child_count
-
-        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

@@ -1,24 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-# 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

@@ -1,128 +0,0 @@
-# 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

@@ -1,12 +0,0 @@
-# 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