tree_haver 5.0.5 → 7.0.0

data/lib/tree_haver/backends/prism.rb

@@ -1,471 +0,0 @@
-# frozen_string_literal: true
-
-module TreeHaver
-  module Backends
-    # Prism backend using Ruby's built-in Prism parser
-    #
-    # This backend wraps Prism, Ruby's official parser (stdlib in Ruby 3.4+,
-    # available as a gem for 3.2+). Unlike tree-sitter backends which are
-    # language-agnostic runtime parsers, Prism is specifically designed for
-    # parsing Ruby source code.
-    #
-    # Prism provides excellent error recovery, detailed location information,
-    # and is the future of Ruby parsing (used by CRuby, JRuby, TruffleRuby).
-    #
-    # @note This backend only parses Ruby source code
-    # @see https://github.com/ruby/prism Prism parser
-    #
-    # @example Basic usage
-    #   parser = TreeHaver::Parser.new
-    #   parser.language = TreeHaver::Backends::Prism::Language.ruby
-    #   tree = parser.parse(ruby_source)
-    #   root = tree.root_node
-    #   puts root.type  # => "program_node"
-    module Prism
-      @load_attempted = false
-      @loaded = false
-
-      # Check if the Prism backend is available
-      #
-      # Attempts to require prism on first call and caches the result.
-      # On Ruby 3.4+, Prism is in stdlib. On 3.2-3.3, it's a gem.
-      #
-      # @return [Boolean] true if prism is available
-      # @example
-      #   if TreeHaver::Backends::Prism.available?
-      #     puts "Prism backend is ready"
-      #   end
-      class << self
-        def available?
-          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
-          begin
-            require "prism"
-            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
-          rescue LoadError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-          rescue StandardError
-            # :nocov: defensive code - StandardError during require is extremely rare
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-            # :nocov:
-          end
-          @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
-        end
-
-        # Reset the load state (primarily for testing)
-        #
-        # @return [void]
-        # @api private
-        def reset!
-          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-        end
-
-        # Get capabilities supported by this backend
-        #
-        # @return [Hash{Symbol => Object}] capability map
-        # @example
-        #   TreeHaver::Backends::Prism.capabilities
-        #   # => { backend: :prism, query: false, bytes_field: true, incremental: false, ruby_only: true }
-        def capabilities
-          return {} unless available?
-          {
-            backend: :prism,
-            query: false,           # Prism doesn't have tree-sitter-style queries (has pattern matching)
-            bytes_field: true,      # Prism provides byte offsets via Location
-            incremental: false,     # Prism doesn't support incremental parsing (yet)
-            pure_ruby: false,       # Prism has native C extension (but also pure Ruby mode)
-            ruby_only: true,        # Prism only parses Ruby source code
-            error_tolerant: true,   # Prism has excellent error recovery
-          }
-        end
-      end
-
-      # Prism language wrapper
-      #
-      # Unlike tree-sitter which supports many languages via grammar files,
-      # Prism only parses Ruby. This class exists for API compatibility with
-      # other tree_haver backends.
-      #
-      # @example
-      #   language = TreeHaver::Backends::Prism::Language.ruby
-      #   parser.language = language
-      class Language < TreeHaver::Base::Language
-        # @param name [Symbol] language name (should be :ruby)
-        # @param options [Hash] Prism parsing options (e.g., frozen_string_literal, version)
-        def initialize(name = :ruby, options: {})
-          super(name, backend: :prism, options: options)
-
-          unless self.name == :ruby
-            raise TreeHaver::NotAvailable,
-              "Prism only supports Ruby parsing. " \
-                "Got language: #{name.inspect}"
-          end
-        end
-
-        # Compare languages for equality by options (since name is always :ruby)
-        #
-        # @param other [Object] object to compare with
-        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
-        def <=>(other)
-          return unless other.is_a?(TreeHaver::Base::Language)
-          return unless other.backend == backend
-
-          options.to_a.sort <=> other.options.to_a.sort
-        end
-
-        class << self
-          # Create a Ruby language instance (convenience method)
-          #
-          # @param options [Hash] Prism parsing options
-          # @option options [Boolean] :frozen_string_literal frozen string literal pragma
-          # @option options [String] :version Ruby version to parse as (e.g., "3.3.0")
-          # @option options [Symbol] :command_line command line option (-e, -n, etc.)
-          # @return [Language]
-          # @example
-          #   lang = TreeHaver::Backends::Prism::Language.ruby
-          #   lang = TreeHaver::Backends::Prism::Language.ruby(frozen_string_literal: true)
-          def ruby(options = {})
-            new(:ruby, options: options)
-          end
-
-          # Load language from library path (API compatibility)
-          #
-          # Prism only supports Ruby, so path and symbol parameters are ignored.
-          #
-          # @param _path [String] Ignored - Prism doesn't load external grammars
-          # @param symbol [String, nil] Ignored - Prism only supports Ruby
-          # @param name [String, nil] Language name hint (defaults to :ruby)
-          # @return [Language] Ruby language
-          # @raise [TreeHaver::NotAvailable] if requested language is not Ruby
-          def from_library(_path = nil, symbol: nil, name: nil)
-            lang_name = name || :ruby
-
-            unless lang_name == :ruby
-              raise TreeHaver::NotAvailable,
-                "Prism backend only supports Ruby, not #{lang_name}. " \
-                  "Use a tree-sitter backend for #{lang_name} support."
-            end
-
-            ruby
-          end
-
-          alias_method :from_path, :from_library
-        end
-      end
-
-      # Prism parser wrapper
-      #
-      # Wraps Prism to provide a tree-sitter-like API for parsing Ruby code.
-      class Parser < TreeHaver::Base::Parser
-        # Create a new Prism parser instance
-        #
-        # @raise [TreeHaver::NotAvailable] if prism is not available
-        def initialize
-          super
-          raise TreeHaver::NotAvailable, "prism not available" unless Prism.available?
-          @options = {}
-        end
-
-        # Set the language for this parser
-        #
-        # Note: TreeHaver::Parser unwraps language objects before calling this method.
-        # This backend receives the Language wrapper (since Prism::Language stores options).
-        #
-        # @param lang [Language, Symbol] Prism language (should be :ruby or Language instance)
-        # @return [void]
-        def language=(lang)
-          case lang
-          when Language
-            @language = lang
-            @options = lang.options
-          when Symbol, String
-            if lang.to_sym == :ruby
-              @language = Language.ruby
-              @options = {}
-            else
-              raise ArgumentError,
-                "Prism only supports Ruby parsing. Got: #{lang.inspect}"
-            end
-          else
-            raise ArgumentError,
-              "Expected Prism::Language or :ruby, got #{lang.class}"
-          end
-        end
-
-        # Parse source code
-        #
-        # @param source [String] the Ruby source code to parse
-        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
-        # @raise [TreeHaver::NotAvailable] if no language is set
-        def parse(source)
-          raise TreeHaver::NotAvailable, "No language loaded (use parser.language = :ruby)" unless @language
-
-          # Use Prism.parse with options
-          prism_result = ::Prism.parse(source, **@options)
-          Tree.new(prism_result, source)
-        end
-
-        # Parse source code (compatibility with tree-sitter API)
-        #
-        # Prism doesn't support incremental parsing, so old_tree is ignored.
-        #
-        # @param old_tree [TreeHaver::Tree, nil] ignored (no incremental parsing support)
-        # @param source [String] the Ruby source code to parse
-        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
-        def parse_string(old_tree, source) # rubocop:disable Lint/UnusedMethodArgument
-          parse(source)  # Prism doesn't support incremental parsing
-        end
-      end
-
-      # Prism tree wrapper
-      #
-      # Wraps a Prism::ParseResult to provide tree-sitter-compatible API.
-      #
-      # @api private
-      class Tree < TreeHaver::Base::Tree
-        # @return [::Prism::ParseResult] the underlying Prism parse result
-        attr_reader :parse_result
-
-        def initialize(parse_result, source)
-          super(parse_result, source: source)
-          @parse_result = parse_result
-        end
-
-        # Get the root node of the parse tree
-        #
-        # @return [Node] wrapped root node
-        def root_node
-          Node.new(@parse_result.value, source)
-        end
-
-        # Check if the parse had errors
-        #
-        # @return [Boolean]
-        def has_errors?
-          @parse_result.failure?
-        end
-
-        # Get parse errors
-        #
-        # @return [Array<::Prism::ParseError>]
-        def errors
-          @parse_result.errors
-        end
-
-        # Get parse warnings
-        #
-        # @return [Array<::Prism::ParseWarning>]
-        def warnings
-          @parse_result.warnings
-        end
-
-        # Get comments from the parse
-        #
-        # @return [Array<::Prism::Comment>]
-        def comments
-          @parse_result.comments
-        end
-
-        # Get magic comments (e.g., frozen_string_literal)
-        #
-        # @return [Array<::Prism::MagicComment>]
-        def magic_comments
-          @parse_result.magic_comments
-        end
-
-        # Get data locations (__END__ section)
-        #
-        # @return [::Prism::Location, nil]
-        def data_loc
-          @parse_result.data_loc
-        end
-      end
-
-      # Prism node wrapper
-      #
-      # Wraps Prism::Node objects to provide tree-sitter-compatible node API.
-      #
-      # Prism nodes provide:
-      # - type: class name without "Node" suffix (e.g., ProgramNode → "program")
-      # - location: ::Prism::Location with start/end offsets and line/column
-      # - child_nodes: array of child nodes
-      # - Various node-specific accessors
-      #
-      # @api private
-      class Node < TreeHaver::Base::Node
-        def initialize(node, source)
-          super(node, source: source)
-        end
-
-        # Get node type from Prism class name
-        #
-        # Converts PrismClassName to tree-sitter-style type string.
-        # Example: CallNode → "call_node", ProgramNode → "program_node"
-        #
-        # @return [String] node type in snake_case
-        def type
-          return "nil" if inner_node.nil?
-
-          # Convert class name to snake_case type
-          class_name = inner_node.class.name.split("::").last
-          class_name.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, "")
-        end
-
-        # Alias for type (API compatibility)
-        # @return [String] node type
-        def kind
-          type
-        end
-
-        # Get byte offset where the node starts
-        #
-        # @return [Integer]
-        def start_byte
-          return 0 if inner_node.nil? || !inner_node.respond_to?(:location)
-          loc = inner_node.location
-          loc&.start_offset || 0
-        end
-
-        # Get byte offset where the node ends
-        #
-        # @return [Integer]
-        def end_byte
-          return 0 if inner_node.nil? || !inner_node.respond_to?(:location)
-          loc = inner_node.location
-          loc&.end_offset || 0
-        end
-
-        # Get the start position as row/column (0-based)
-        #
-        # @return [Hash{Symbol => Integer}]
-        def start_point
-          return {row: 0, column: 0} if inner_node.nil? || !inner_node.respond_to?(:location)
-          loc = inner_node.location
-          return {row: 0, column: 0} unless loc
-
-          {row: (loc.start_line - 1), column: loc.start_column}
-        end
-
-        # Get the end position as row/column (0-based)
-        #
-        # @return [Hash{Symbol => Integer}]
-        def end_point
-          return {row: 0, column: 0} if inner_node.nil? || !inner_node.respond_to?(:location)
-          loc = inner_node.location
-          return {row: 0, column: 0} unless loc
-
-          {row: (loc.end_line - 1), column: loc.end_column}
-        end
-
-        # Get all child nodes
-        #
-        # @return [Array<Node>] array of wrapped child nodes
-        def children
-          return [] if inner_node.nil?
-          return [] unless inner_node.respond_to?(:child_nodes)
-
-          inner_node.child_nodes.compact.map { |n| Node.new(n, source) }
-        end
-
-        # Get the text content of this node
-        #
-        # @return [String]
-        def text
-          return "" if inner_node.nil?
-
-          if inner_node.respond_to?(:slice)
-            inner_node.slice
-          else
-            super
-          end
-        end
-
-        # Alias for Prism compatibility
-        alias_method :slice, :text
-
-        # Check if this node has errors
-        #
-        # @return [Boolean]
-        def has_error?
-          return false if inner_node.nil?
-
-          # Check if this is an error node type
-          return true if type.include?("missing") || type.include?("error")
-
-          # Check children recursively (Prism error nodes are usually children)
-          return false unless inner_node.respond_to?(:child_nodes)
-          inner_node.child_nodes.compact.any? { |n| n.class.name.to_s.include?("Missing") }
-        end
-
-        # Check if this node is a "missing" node (error recovery)
-        #
-        # @return [Boolean]
-        def missing?
-          return false if inner_node.nil?
-          type.include?("missing")
-        end
-
-        # Get a child by field name (Prism node accessor)
-        #
-        # Prism nodes have specific accessors for their children.
-        #
-        # @param name [String, Symbol] field/accessor name
-        # @return [Node, nil] wrapped child node
-        def child_by_field_name(name)
-          return if inner_node.nil?
-          return unless inner_node.respond_to?(name)
-
-          result = inner_node.public_send(name)
-          return if result.nil?
-
-          # Wrap if it's a node
-          result.is_a?(::Prism::Node) ? Node.new(result, source) : nil
-        end
-
-        alias_method :field, :child_by_field_name
-
-        # String representation
-        #
-        # @return [String]
-        def to_s
-          text
-        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)
-          return false if inner_node.nil?
-          inner_node.respond_to?(method_name, include_private) || super
-        end
-
-        # Delegate unknown methods to the underlying Prism node
-        #
-        # This provides passthrough access for Prism-specific node methods
-        # like `receiver`, `message`, `arguments`, etc.
-        #
-        # @param method_name [Symbol] method to call
-        # @param args [Array] arguments to pass
-        # @param kwargs [Hash] keyword arguments
-        # @param block [Proc] block to pass
-        # @return [Object] result from the underlying node
-        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
-
-      # Register the availability checker for RSpec dependency tags
-      TreeHaver::BackendRegistry.register_availability_checker(:prism) do
-        available?
-      end
-    end
-  end
-end
-