tree_haver 3.0.0 → 3.1.0

data/lib/tree_haver/backends/psych.rb

@@ -0,0 +1,597 @@
+# 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
+          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
+          }
+        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
+        include Comparable
+
+        # The language name (always :yaml for Psych)
+        # @return [Symbol]
+        attr_reader :name
+
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # Create a new Psych language instance
+        #
+        # @param name [Symbol] Language name (should be :yaml)
+        def initialize(name = :yaml)
+          @name = name.to_sym
+          @backend = :psych
+        end
+
+        class << self
+          # Create a YAML language instance
+          #
+          # @return [Language] YAML language
+          def yaml
+            new(:yaml)
+          end
+        end
+
+        # Comparison for sorting/equality
+        #
+        # @param other [Language] other language
+        # @return [Integer, nil] comparison result
+        def <=>(other)
+          return unless other.is_a?(Language)
+          name <=> other.name
+        end
+
+        # @return [String] human-readable representation
+        def inspect
+          "#<TreeHaver::Backends::Psych::Language name=#{name}>"
+        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
+        # @return [Language, nil] The language to parse
+        attr_accessor :language
+
+        # Create a new Psych parser
+        def initialize
+          @language = nil
+        end
+
+        # 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
+        # @return [::Psych::Nodes::Stream] The underlying Psych stream
+        attr_reader :inner_tree
+
+        # @return [String] The original source
+        attr_reader :source
+
+        # Create a new tree wrapper
+        #
+        # @param stream [::Psych::Nodes::Stream] Psych stream node
+        # @param source [String] Original source
+        def initialize(stream, source)
+          @inner_tree = stream
+          @source = source
+          @lines = source.lines
+        end
+
+        # Get the root node
+        #
+        # For YAML, the stream is the root. We wrap it as a Node.
+        #
+        # @return [Node] Root node
+        def root_node
+          Node.new(@inner_tree, @source, @lines)
+        end
+
+        # Get parse errors
+        #
+        # Psych raises exceptions on parse errors rather than recording them,
+        # so this is always empty if we got a tree.
+        #
+        # @return [Array] Empty array (no errors if parsing succeeded)
+        def errors
+          []
+        end
+
+        # Get parse warnings
+        #
+        # @return [Array] Empty array (Psych doesn't produce warnings)
+        def warnings
+          []
+        end
+
+        # Get comments from the document
+        #
+        # Psych doesn't preserve comments in the AST by default.
+        #
+        # @return [Array] Empty array
+        def comments
+          []
+        end
+
+        # @return [String] 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)
+      # - Alias: YAML anchor reference
+      class Node
+        include Comparable
+
+        # @return [::Psych::Nodes::Node] The underlying Psych node
+        attr_reader :inner_node
+
+        # @return [String] The original source
+        attr_reader :source
+
+        # Create a new node wrapper
+        #
+        # @param node [::Psych::Nodes::Node] Psych node
+        # @param source [String] Original source
+        # @param lines [Array<String>] Source lines for text extraction
+        def initialize(node, source, lines = nil)
+          @inner_node = node
+          @source = source
+          @lines = lines || source.lines
+        end
+
+        # Get the node type as a string
+        #
+        # Maps Psych class names to lowercase type strings:
+        # - Psych::Nodes::Stream → "stream"
+        # - Psych::Nodes::Document → "document"
+        # - Psych::Nodes::Mapping → "mapping"
+        # - Psych::Nodes::Sequence → "sequence"
+        # - Psych::Nodes::Scalar → "scalar"
+        # - Psych::Nodes::Alias → "alias"
+        #
+        # @return [String] Node type
+        def type
+          @inner_node.class.name.split("::").last.downcase
+        end
+
+        # Alias for tree-sitter compatibility
+        alias_method :kind, :type
+
+        # Get the text content of this node
+        #
+        # For Scalar nodes, returns the value. For containers, returns
+        # the source text spanning the node's location.
+        #
+        # @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, @lines) }
+        end
+
+        # Iterate over child nodes
+        #
+        # @yield [Node] Each child node
+        # @return [Enumerator, nil]
+        def each(&block)
+          return to_enum(__method__) unless block
+          children.each(&block)
+        end
+
+        # Get the number of children
+        #
+        # @return [Integer] Child count
+        def child_count
+          children.size
+        end
+
+        # Get child by index
+        #
+        # @param index [Integer] Child index
+        # @return [Node, nil] Child node
+        def child(index)
+          children[index]
+        end
+
+        # Get start byte offset
+        #
+        # Psych doesn't provide byte offsets directly, so we calculate from line/column.
+        #
+        # @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)
+        #
+        # @return [Point] Start position (0-based)
+        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
+          Point.new(row, col)
+        end
+
+        # Get end point (row, column)
+        #
+        # @return [Point] End position (0-based)
+        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
+          Point.new(row, col)
+        end
+
+        # Get the 1-based line number where this node starts
+        #
+        # Psych provides 0-based line numbers, so we add 1.
+        #
+        # @return [Integer] 1-based line number
+        def start_line
+          row = start_point.row
+          row + 1
+        end
+
+        # Get the 1-based line number where this node ends
+        #
+        # @return [Integer] 1-based line number
+        def end_line
+          row = end_point.row
+          row + 1
+        end
+
+        # Get position information as a hash
+        #
+        # Returns a hash with 1-based line numbers and 0-based columns.
+        # Compatible with *-merge gems' FileAnalysisBase.
+        #
+        # @return [Hash{Symbol => Integer}] Position hash
+        def source_position
+          {
+            start_line: start_line,
+            end_line: end_line,
+            start_column: start_point.column,
+            end_column: end_point.column,
+          }
+        end
+
+        # Get the first child node
+        #
+        # @return [Node, nil] First child or nil
+        def first_child
+          children.first
+        end
+
+        # Check if this is a named (structural) node
+        #
+        # All Psych nodes are structural.
+        #
+        # @return [Boolean] true
+        def named?
+          true
+        end
+
+        # Alias for tree-sitter compatibility
+        alias_method :structural?, :named?
+
+        # Check if the node or any descendant has an error
+        #
+        # Psych raises on errors rather than embedding them.
+        #
+        # @return [Boolean] false
+        def has_error?
+          false
+        end
+
+        # Check if this is a missing node
+        #
+        # Psych doesn't have missing nodes.
+        #
+        # @return [Boolean] false
+        def missing?
+          false
+        end
+
+        # Comparison for sorting
+        #
+        # @param other [Node] other node
+        # @return [Integer, nil] comparison result
+        def <=>(other)
+          return unless other.respond_to?(:start_byte)
+          cmp = start_byte <=> other.start_byte
+          return cmp unless cmp&.zero?
+          end_byte <=> other.end_byte
+        end
+
+        # @return [String] human-readable representation
+        def inspect
+          "#<TreeHaver::Backends::Psych::Node type=#{type} children=#{child_count}>"
+        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
+
+        # Calculate byte offset from line and column
+        #
+        # @param line [Integer] 0-based line number
+        # @param column [Integer] 0-based column
+        # @return [Integer] Byte offset
+        def calculate_byte_offset(line, column)
+          offset = 0
+          @lines.each_with_index do |line_content, idx|
+            if idx < line
+              offset += line_content.bytesize
+              offset += 1 unless line_content.end_with?("\n") # Add newline
+            else
+              offset += [column, line_content.bytesize].min
+              break
+            end
+          end
+          offset
+        end
+
+        # 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_line = @inner_node.start_line || 0
+          end_line = @inner_node.end_line || start_line
+          start_col = @inner_node.start_column || 0
+          end_col = @inner_node.end_column || 0
+
+          if start_line == end_line
+            line = @lines[start_line] || ""
+            line[start_col...end_col] || ""
+          else
+            result = []
+            (start_line..end_line).each do |ln|
+              line = @lines[ln] || ""
+              result << if ln == start_line
+                line[start_col..]
+              elsif ln == end_line
+                line[0...end_col]
+              else
+                line
+              end
+            end
+            result.compact.join
+          end
+        end
+      end
+
+      # Point struct for position information
+      #
+      # Provides both method and hash-style access for compatibility.
+      Point = Struct.new(:row, :column) do
+        # Hash-like access
+        #
+        # @param key [Symbol, String] :row or :column
+        # @return [Integer, nil]
+        def [](key)
+          case key
+          when :row, "row" then row
+          when :column, "column" then column
+          end
+        end
+
+        # @return [Hash]
+        def to_h
+          {row: row, column: column}
+        end
+
+        # @return [String]
+        def to_s
+          "(#{row}, #{column})"
+        end
+
+        # @return [String]
+        def inspect
+          "#<TreeHaver::Backends::Psych::Point row=#{row} column=#{column}>"
+        end
+      end
+    end
+  end
+end

data/lib/tree_haver/backends/rust.rb

@@ -175,7 +175,7 @@ module TreeHaver
           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
+          lang # rubocop:disable Lint/Void (intentional return value)
         end
 
         # Parse source code

data/lib/tree_haver/grammar_finder.rb

@@ -137,12 +137,25 @@ module TreeHaver
     # @note Paths from ENV are validated using {PathValidator.safe_library_path?}
     #   to prevent path traversal and other attacks. Invalid ENV paths are ignored.
     #
+    # @note Setting the ENV variable to an empty string explicitly disables
+    #   this grammar. This allows fallback to alternative backends (e.g., Citrus).
+    #
     # @return [String, nil] the path to the library, or nil if not found
     # @see #find_library_path_safe For stricter validation (trusted directories only)
     def find_library_path
       # Check environment variable first (highest priority)
-      env_path = ENV[env_var_name]
-      if env_path
+      # Use key? to distinguish between "not set" and "set to empty"
+      if ENV.key?(env_var_name)
+        env_path = ENV[env_var_name]
+
+        # Empty string means "explicitly skip this grammar"
+        # This allows users to disable tree-sitter for specific languages
+        # and fall back to alternative backends like Citrus
+        if env_path.empty?
+          @env_rejection_reason = "explicitly disabled (set to empty string)"
+          return
+        end
+
         # Store why env path was rejected for better error messages
         @env_rejection_reason = validate_env_path(env_path)
         return env_path if @env_rejection_reason.nil?
@@ -188,11 +201,67 @@ module TreeHaver
       end
     end
 
-    # Check if the grammar library is available
+    # Check if the grammar library is available AND usable
+    #
+    # This checks:
+    # 1. The grammar library file exists
+    # 2. The tree-sitter runtime is functional (can create a parser)
     #
-    # @return [Boolean] true if the library can be found
+    # This prevents registering grammars when tree-sitter isn't actually usable,
+    # allowing clean fallback to alternative backends like Citrus.
+    #
+    # @return [Boolean] true if the library can be found AND tree-sitter runtime works
     def available?
-      !find_library_path.nil?
+      path = find_library_path
+      return false if path.nil?
+
+      # Check if tree-sitter runtime is actually functional
+      # This is cached at the class level since it's the same for all grammars
+      self.class.tree_sitter_runtime_usable?
+    end
+
+    # Backends that use tree-sitter (require native runtime libraries)
+    # Other backends (Citrus, Prism, Psych, etc.) don't use tree-sitter
+    TREE_SITTER_BACKENDS = [
+      TreeHaver::Backends::MRI,
+      TreeHaver::Backends::FFI,
+      TreeHaver::Backends::Rust,
+      TreeHaver::Backends::Java,
+    ].freeze
+
+    class << self
+      # Check if the tree-sitter runtime is usable
+      #
+      # Tests whether we can actually create a tree-sitter parser.
+      # Result is cached since this is expensive and won't change during runtime.
+      #
+      # @return [Boolean] true if tree-sitter runtime is functional
+      def tree_sitter_runtime_usable?
+        return @tree_sitter_runtime_usable if defined?(@tree_sitter_runtime_usable)
+
+        @tree_sitter_runtime_usable = begin
+          # Try to create a parser using the current backend
+          mod = TreeHaver.resolve_backend_module(nil)
+
+          # Only tree-sitter backends are relevant here
+          # Non-tree-sitter backends (Citrus, Prism, Psych, etc.) don't use grammar files
+          return false if mod.nil?
+          return false unless TREE_SITTER_BACKENDS.include?(mod)
+
+          # Try to instantiate a parser - this will fail if runtime isn't available
+          mod::Parser.new
+          true
+        rescue NoMethodError, FFI::NotFoundError, LoadError, NotAvailable => _e
+          false
+        end
+      end
+
+      # Reset the cached tree-sitter runtime check (for testing)
+      #
+      # @api private
+      def reset_runtime_check!
+        remove_instance_variable(:@tree_sitter_runtime_usable) if defined?(@tree_sitter_runtime_usable)
+      end
     end
 
     # Check if the grammar library is available in a trusted directory