tree_haver 7.0.0 → 7.1.0

data/lib/tree_haver/backends/psych.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Backends
+    # Psych backend using Ruby's built-in YAML parser
+    #
+    # This backend wraps Psych, Ruby's standard library YAML parser.
+    # Psych provides AST access via Psych.parse_stream which returns
+    # Psych::Nodes::* objects (Stream, Document, Mapping, Sequence, Scalar, Alias).
+    #
+    # @note This backend only parses YAML source code
+    # @see https://ruby-doc.org/stdlib/libdoc/psych/rdoc/Psych.html Psych documentation
+    #
+    # @example Basic usage
+    #   parser = TreeHaver::Parser.new
+    #   parser.language = TreeHaver::Backends::Psych::Language.yaml
+    #   tree = parser.parse(yaml_source)
+    #   root = tree.root_node
+    #   puts root.type  # => "stream"
+    module Psych
+      @load_attempted = false
+      @loaded = false
+
+      # Check if the Psych backend is available
+      #
+      # Psych is part of Ruby stdlib, so it should always be available.
+      #
+      # @return [Boolean] true if psych is available
+      class << self
+        def available?
+          return @loaded if @load_attempted
+
+          @load_attempted = true
+          begin
+            require 'psych'
+            @loaded = true
+          rescue LoadError
+            @loaded = false
+          rescue StandardError
+            # simplecov:disable defensive code - StandardError during require is extremely rare
+            @loaded = false
+            # simplecov:enable
+          end
+          @loaded
+        end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false
+          @loaded = false
+        end
+
+        # Get capabilities supported by this backend
+        #
+        # @return [Hash{Symbol => Object}] capability map
+        def capabilities
+          return {} unless available?
+
+          {
+            backend: :psych,
+            query: false,           # Psych doesn't have tree-sitter-style queries
+            bytes_field: false,     # Psych uses line/column, not byte offsets
+            incremental: false,     # Psych doesn't support incremental parsing
+            pure_ruby: false,       # Psych has native libyaml C extension
+            yaml_only: true,        # Psych only parses YAML
+            error_tolerant: false,  # Psych raises on syntax errors
+            comment_support: :none
+          }
+        end
+      end
+
+      # Psych language wrapper
+      #
+      # Unlike tree-sitter which supports many languages via grammar files,
+      # Psych only parses YAML. This class exists for API compatibility with
+      # other tree_haver backends.
+      #
+      # @example
+      #   language = TreeHaver::Backends::Psych::Language.yaml
+      #   parser.language = language
+      class Language < TreeHaver::Base::Language
+        # Create a new Psych language instance
+        #
+        # @param name [Symbol] Language name (should be :yaml)
+        def initialize(name = :yaml)
+          super(name, backend: :psych, options: {})
+        end
+
+        class << self
+          # Create a YAML language instance
+          #
+          # @return [Language] YAML language
+          def yaml
+            new(:yaml)
+          end
+
+          # Load language from library path (API compatibility)
+          #
+          # Psych only supports YAML, so path and symbol parameters are ignored.
+          #
+          # @param _path [String] Ignored - Psych doesn't load external grammars
+          # @param symbol [String, nil] Ignored - Psych only supports YAML
+          # @param name [String, nil] Language name hint (defaults to :yaml)
+          # @return [Language] YAML language
+          # @raise [TreeHaver::NotAvailable] if requested language is not YAML
+          def from_library(_path = nil, symbol: nil, name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            lang_name = name || :yaml
+
+            unless lang_name == :yaml
+              raise TreeHaver::NotAvailable,
+                    "Psych backend only supports YAML, not #{lang_name}. " \
+                      "Use a tree-sitter backend for #{lang_name} support."
+            end
+
+            yaml
+          end
+        end
+      end
+
+      # Psych parser wrapper
+      #
+      # Wraps Psych.parse_stream to provide TreeHaver-compatible parsing.
+      #
+      # @example
+      #   parser = TreeHaver::Backends::Psych::Parser.new
+      #   parser.language = Language.yaml
+      #   tree = parser.parse(yaml_source)
+      class Parser < TreeHaver::Base::Parser
+        # Parse YAML source code
+        #
+        # @param source [String] YAML source to parse
+        # @return [Tree] Parsed tree
+        # @raise [::Psych::SyntaxError] on syntax errors
+        def parse(source)
+          raise 'Language not set' unless language
+
+          Psych.available? or raise 'Psych not available'
+
+          ast = ::Psych.parse_stream(source)
+          Tree.new(ast, source)
+        end
+
+        # Alias for compatibility with tree-sitter API
+        #
+        # @param _old_tree [nil] Ignored (Psych doesn't support incremental parsing)
+        # @param source [String] YAML source to parse
+        # @return [Tree] Parsed tree
+        def parse_string(_old_tree, source)
+          parse(source)
+        end
+      end
+
+      # Psych tree wrapper
+      #
+      # Wraps a Psych::Nodes::Stream to provide TreeHaver-compatible tree interface.
+      class Tree < TreeHaver::Base::Tree
+        # @return [::Psych::Nodes::Stream] The underlying Psych stream
+        attr_reader :inner_tree
+
+        # Create a new tree wrapper
+        #
+        # @param stream [::Psych::Nodes::Stream] Psych stream node
+        # @param source [String] Original source
+        def initialize(stream, source)
+          super(stream, source: source)
+        end
+
+        # Get the root node
+        #
+        # @return [Node] Root node
+        def root_node
+          Node.new(inner_tree, source: source, lines: lines)
+        end
+
+        # Human-readable representation
+        def inspect
+          "#<TreeHaver::Backends::Psych::Tree documents=#{inner_tree.children&.size || 0}>"
+        end
+      end
+
+      # Psych node wrapper
+      #
+      # Wraps Psych::Nodes::* classes to provide TreeHaver::Node-compatible interface.
+      #
+      # Psych node types:
+      # - Stream: Root container
+      # - Document: YAML document (multiple per stream possible)
+      # - Mapping: Hash/object
+      # - Sequence: Array/list
+      # - Scalar: Primitive value (string, number, boolean, null)
+      # - Psych::Nodes::Alias: YAML anchor reference
+      class Node < TreeHaver::Base::Node
+        # Get the node type as a string
+        #
+        # @return [String] Node type
+        def type
+          inner_node.class.name.split('::').last.downcase
+        end
+
+        # Alias for type (API compatibility)
+        # @return [String] node type
+        def kind
+          type
+        end
+
+        # Get the text content of this node
+        #
+        # @return [String] Node text
+        def text
+          case inner_node
+          when ::Psych::Nodes::Scalar
+            inner_node.value.to_s
+          when ::Psych::Nodes::Alias
+            "*#{inner_node.anchor}"
+          else
+            # For container nodes, extract from source using location
+            extract_text_from_location
+          end
+        end
+
+        # Get child nodes
+        #
+        # @return [Array<Node>] Child nodes
+        def children
+          return [] unless inner_node.respond_to?(:children) && inner_node.children
+
+          inner_node.children.map { |child| Node.new(child, source: source, lines: lines) }
+        end
+
+        # Get start byte offset
+        #
+        # @return [Integer] Start byte offset
+        def start_byte
+          return 0 unless inner_node.respond_to?(:start_line)
+
+          line = inner_node.start_line || 0
+          col = inner_node.start_column || 0
+          calculate_byte_offset(line, col)
+        end
+
+        # Get end byte offset
+        #
+        # @return [Integer] End byte offset
+        def end_byte
+          return start_byte + text.bytesize unless inner_node.respond_to?(:end_line)
+
+          line = inner_node.end_line || 0
+          col = inner_node.end_column || 0
+          calculate_byte_offset(line, col)
+        end
+
+        # Get start point (row, column) - 0-based
+        #
+        # @return [TreeHaver::Base::Point] Start position
+        def start_point
+          row = (inner_node.respond_to?(:start_line) ? inner_node.start_line : 0) || 0
+          col = (inner_node.respond_to?(:start_column) ? inner_node.start_column : 0) || 0
+          TreeHaver::Base::Point.new(row, col)
+        end
+
+        # Get end point (row, column) - 0-based
+        #
+        # @return [TreeHaver::Base::Point] End position
+        def end_point
+          row = (inner_node.respond_to?(:end_line) ? inner_node.end_line : 0) || 0
+          col = (inner_node.respond_to?(:end_column) ? inner_node.end_column : 0) || 0
+          TreeHaver::Base::Point.new(row, col)
+        end
+
+        # Psych-specific: Get the anchor name for Alias/anchored nodes
+        #
+        # @return [String, nil] Anchor name
+        def anchor
+          inner_node.anchor if inner_node.respond_to?(:anchor)
+        end
+
+        # Psych-specific: Get the tag for tagged nodes
+        #
+        # @return [String, nil] Tag
+        def tag
+          inner_node.tag if inner_node.respond_to?(:tag)
+        end
+
+        # Psych-specific: Get the scalar value
+        #
+        # @return [String, nil] Value for scalar nodes
+        def value
+          inner_node.value if inner_node.respond_to?(:value)
+        end
+
+        # Psych-specific: Check if this is a mapping (hash)
+        #
+        # @return [Boolean]
+        def mapping?
+          inner_node.is_a?(::Psych::Nodes::Mapping)
+        end
+
+        # Psych-specific: Check if this is a sequence (array)
+        #
+        # @return [Boolean]
+        def sequence?
+          inner_node.is_a?(::Psych::Nodes::Sequence)
+        end
+
+        # Psych-specific: Check if this is a scalar (primitive)
+        #
+        # @return [Boolean]
+        def scalar?
+          inner_node.is_a?(::Psych::Nodes::Scalar)
+        end
+
+        # Psych-specific: Check if this is an alias
+        #
+        # @return [Boolean]
+        def alias?
+          inner_node.is_a?(::Psych::Nodes::Alias)
+        end
+
+        # Psych-specific: Get mapping entries as key-value pairs
+        #
+        # For Mapping nodes, children alternate key, value, key, value...
+        #
+        # @return [Array<Array(Node, Node)>] Key-value pairs
+        def mapping_entries
+          return [] unless mapping?
+
+          pairs = []
+          children.each_slice(2) do |key, val|
+            pairs << [key, val] if key && val
+          end
+          pairs
+        end
+
+        private
+
+        # Extract text from source using location
+        #
+        # @return [String] Extracted text
+        def extract_text_from_location
+          return '' unless inner_node.respond_to?(:start_line) && inner_node.respond_to?(:end_line)
+
+          start_ln = inner_node.start_line || 0
+          end_ln = inner_node.end_line || start_ln
+          start_col = inner_node.start_column || 0
+          end_col = inner_node.end_column || 0
+
+          if start_ln == end_ln
+            line = lines[start_ln] || ''
+            line[start_col...end_col] || ''
+          else
+            result = []
+            (start_ln..end_ln).each do |ln|
+              line = lines[ln] || ''
+              result << if ln == start_ln
+                          line[start_col..]
+                        elsif ln == end_ln
+                          line[0...end_col]
+                        else
+                          line
+                        end
+            end
+            result.compact.join
+          end
+        end
+      end
+
+      # Alias Point to the base class for compatibility
+      Point = TreeHaver::Base::Point
+
+      # Register the availability checker for RSpec dependency tags
+      TreeHaver::BackendRegistry.register_availability_checker(:psych) do
+        available?
+      end
+    end
+  end
+end

data/lib/tree_haver/backends/rust.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Backends
+    # Rust backend using the tree_stump gem
+    #
+    # This backend wraps the tree_stump gem, which provides Ruby bindings to
+    # tree-sitter written in Rust. It offers native performance with Rust's
+    # safety guarantees and includes precompiled binaries for common platforms.
+    #
+    # tree_stump supports incremental parsing and the Query API, making it
+    # suitable for editor/IDE use cases where performance is critical.
+    #
+    # == Tree/Node Architecture
+    #
+    # This backend (like all tree-sitter backends: MRI, Rust, FFI, Java) does NOT
+    # define its own Tree or Node classes. Instead:
+    #
+    # - Parser#parse returns raw `::TreeStump::Tree` objects
+    # - These are wrapped by `TreeHaver::Tree` (inherits from `Base::Tree`)
+    # - `TreeHaver::Tree#root_node` wraps raw nodes in `TreeHaver::Node`
+    #
+    # This differs from pure-Ruby backends (Citrus, Prism, Psych) which define
+    # their own `Backend::X::Tree` and `Backend::X::Node` classes.
+    #
+    # @see TreeHaver::Tree The wrapper class for tree-sitter Tree objects
+    # @see TreeHaver::Node The wrapper class for tree-sitter Node objects
+    # @see TreeHaver::Base::Tree Base class documenting the Tree API contract
+    # @see TreeHaver::Base::Node Base class documenting the Node API contract
+    #
+    # == Platform Compatibility
+    #
+    # - MRI Ruby: ✓ Full support
+    # - JRuby: ✗ Cannot load native extensions (runs on JVM)
+    # - TruffleRuby: ✗ magnus/rb-sys incompatible with TruffleRuby's C API emulation
+    #
+    # @see https://github.com/joker1007/tree_stump tree_stump
+    module Rust
+      @load_attempted = false
+      @loaded = false
+
+      # Check if the Rust backend is available
+      #
+      # Attempts to require tree_stump on first call and caches the result.
+      #
+      # @return [Boolean] true if tree_stump is available
+      # @example
+      #   if TreeHaver::Backends::Rust.available?
+      #     puts "Rust backend is ready"
+      #   end
+      class << self
+        def available?
+          return @loaded if @load_attempted
+
+          @load_attempted = true
+          begin
+            # tree_stump uses magnus which requires MRI's C API
+            # It doesn't work on JRuby or TruffleRuby
+            if RUBY_ENGINE == 'ruby'
+              require 'tree_stump'
+              @loaded = true
+            else
+              @loaded = false
+            end
+          rescue LoadError
+            @loaded = false
+          rescue StandardError
+            @loaded = false
+          end
+          @loaded
+        end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false
+          @loaded = false
+        end
+
+        # Get capabilities supported by this backend
+        #
+        # @return [Hash{Symbol => Object}] capability map
+        # @example
+        #   TreeHaver::Backends::Rust.capabilities
+        #   # => { backend: :rust, query: true, bytes_field: true, incremental: false, comment_support: :nodes_only }
+        def capabilities
+          return {} unless available?
+
+          {
+            backend: :rust,
+            query: true,
+            bytes_field: true,
+            incremental: false, # TreeStump doesn't currently expose incremental parsing to Ruby
+            comment_support: :nodes_only
+          }
+        end
+      end
+
+      # Wrapper for tree_stump Language
+      #
+      # Provides TreeHaver-compatible interface to tree_stump's language loading.
+      # tree_stump uses a registration-based API where languages are registered
+      # by name, then referenced by that name when setting parser language.
+      class Language
+        include Comparable
+
+        # The registered language name
+        # @return [String]
+        attr_reader :name
+
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
+        # @api private
+        # @param name [String] the registered language name
+        # @param path [String, nil] path language was loaded from
+        def initialize(name, path: nil)
+          @name = name
+          @backend = :rust
+          @path = path
+        end
+
+        # Compare languages for equality
+        #
+        # Rust languages are equal if they have the same backend and name.
+        # Name uniquely identifies a registered language in TreeStump.
+        #
+        # @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?(Language)
+          return unless other.backend == @backend
+
+          @name <=> other.name
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @name].hash
+        end
+
+        # Alias eql? to ==
+        alias eql? ==
+
+        # Load a language from a shared library path
+        #
+        # @param path [String] absolute path to the language shared library
+        # @param symbol [String, nil] the symbol name (accepted for API consistency, but tree_stump derives it from name)
+        # @param name [String, nil] logical name for the language (optional, derived from path if not provided)
+        # @return [Language] a wrapper holding the registered language name
+        # @raise [TreeHaver::NotAvailable] if tree_stump is not available
+        # @example
+        #   lang = TreeHaver::Backends::Rust::Language.from_library("/usr/local/lib/libtree-sitter-toml.so")
+        class << self
+          def from_library(path, symbol: nil, name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            raise TreeHaver::NotAvailable, 'tree_stump not available' unless Rust.available?
+
+            # Validate the path exists before calling register_lang to provide a clear error
+            raise TreeHaver::NotAvailable, "Language library not found: #{path}" unless File.exist?(path)
+
+            # tree_stump uses TreeStump.register_lang(name, path) to register languages
+            # The name is used to derive the symbol automatically (tree_sitter_<name>)
+            # Use shared utility for consistent path parsing across backends
+            lang_name = name || LibraryPathUtils.derive_language_name_from_path(path)
+            ::TreeStump.register_lang(lang_name, path)
+            new(lang_name, path: path)
+          rescue RuntimeError => e
+            raise TreeHaver::NotAvailable, "Failed to load language from #{path}: #{e.message}"
+          end
+
+          # Backward-compatible alias for from_library
+          alias from_path from_library
+        end
+      end
+
+      # Wrapper for tree_stump Parser
+      #
+      # Provides TreeHaver-compatible interface to tree_stump's parser.
+      class Parser
+        # Create a new parser instance
+        #
+        # @raise [TreeHaver::NotAvailable] if tree_stump is not available
+        def initialize
+          raise TreeHaver::NotAvailable, 'tree_stump not available' unless Rust.available?
+
+          @parser = ::TreeStump::Parser.new
+        end
+
+        # Set the language for this parser
+        #
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # When called from TreeHaver::Parser, receives String (language name).
+        # For backward compatibility and backend tests, also handles Language wrapper.
+        #
+        # @param lang [Language, String] the language wrapper or name string
+        # @return [Language, String] the language that was set
+        def language=(lang)
+          # Extract language name (handle both wrapper and raw string)
+          lang_name = lang.respond_to?(:name) ? lang.name : lang.to_s
+          # tree_stump uses set_language with a string name
+          @parser.set_language(lang_name)
+          lang # rubocop:disable Lint/Void (intentional return value)
+        end
+
+        # Parse source code
+        #
+        # @param source [String] the source code to parse
+        # @return [TreeStump::Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
+        def parse(source)
+          # Return raw tree_stump tree - TreeHaver::Parser will wrap it
+          @parser.parse(source)
+        end
+
+        # Parse source code with optional incremental parsing
+        #
+        # Note: TreeStump does not currently expose incremental parsing to Ruby.
+        # The parse method always does a full parse, ignoring old_tree.
+        #
+        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing (ignored)
+        # @param source [String] the source code to parse
+        # @return [TreeStump::Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
+        def parse_string(old_tree, source) # rubocop:disable Lint/UnusedMethodArgument
+          # TreeStump's parse method only accepts source as a single argument
+          # and internally always passes None for the old tree (no incremental parsing support)
+          @parser.parse(source)
+        end
+      end
+
+      # Register the availability checker for RSpec dependency tags
+      TreeHaver::BackendRegistry.register_availability_checker(:rust) do
+        available?
+      end
+    end
+  end
+end