tree_haver 5.0.4 → 7.0.0

data/lib/tree_haver/backends/psych.rb

@@ -1,375 +0,0 @@
-# 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 # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
-          begin
-            require "psych"
-            @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
-        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
-          }
-        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

@@ -1,239 +0,0 @@
-# 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 # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
-          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 # rubocop:disable ThreadSafety/ClassInstanceVariable
-            else
-              @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-            end
-          rescue LoadError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-          rescue StandardError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-          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::Rust.capabilities
-        #   # => { backend: :rust, query: true, bytes_field: true, incremental: false }
-        def capabilities
-          return {} unless available?
-          {
-            backend: :rust,
-            query: true,
-            bytes_field: true,
-            incremental: false,  # TreeStump doesn't currently expose incremental parsing to Ruby
-          }
-        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_method :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_method :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