tree_haver 5.0.4 → 7.0.0

data/lib/tree_haver/backends/citrus.rb

@@ -1,487 +0,0 @@
-# frozen_string_literal: true
-
-module TreeHaver
-  module Backends
-    # Citrus backend using pure Ruby PEG parser
-    #
-    # This backend wraps Citrus-based parsers (like toml-rb) to provide a
-    # pure Ruby alternative to tree-sitter. Citrus is a PEG (Parsing Expression
-    # Grammar) parser generator written in Ruby.
-    #
-    # Unlike tree-sitter backends which are language-agnostic runtime parsers,
-    # Citrus parsers are grammar-specific and compiled into Ruby code. Each
-    # language needs its own Citrus grammar (e.g., toml-rb for TOML).
-    #
-    # @note This backend requires a Citrus grammar for the specific language
-    # @see https://github.com/mjackson/citrus Citrus parser generator
-    # @see https://github.com/emancu/toml-rb toml-rb (TOML Citrus grammar)
-    #
-    # @example Using with toml-rb
-    #   require "toml-rb"
-    #
-    #   parser = TreeHaver::Parser.new
-    #   # For Citrus, "language" is actually a grammar module
-    #   parser.language = TomlRB::Document
-    #   tree = parser.parse(toml_source)
-    module Citrus
-      @load_attempted = false
-      @loaded = false
-
-      # Check if the Citrus backend is available
-      #
-      # Attempts to require citrus on first call and caches the result.
-      #
-      # @return [Boolean] true if citrus gem is available
-      # @example
-      #   if TreeHaver::Backends::Citrus.available?
-      #     puts "Citrus 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 "citrus"
-            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
-          rescue LoadError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-            # :nocov: defensive code - StandardError during require is extremely rare
-          rescue StandardError
-            @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::Citrus.capabilities
-        #   # => { backend: :citrus, query: false, bytes_field: true, incremental: false }
-        def capabilities
-          return {} unless available?
-          {
-            backend: :citrus,
-            query: false,          # Citrus doesn't have a query API like tree-sitter
-            bytes_field: true,     # Citrus::Match provides offset and length
-            incremental: false,    # Citrus doesn't support incremental parsing
-            pure_ruby: true,       # Citrus is pure Ruby (portable)
-          }
-        end
-      end
-
-      # Citrus grammar wrapper
-      #
-      # Unlike tree-sitter which loads compiled .so files, Citrus uses Ruby modules
-      # that define grammars. This class wraps a Citrus grammar module.
-      #
-      # @example
-      #   # For TOML, use toml-rb's grammar
-      #   language = TreeHaver::Backends::Citrus::Language.new(TomlRB::Document)
-      class Language
-        include Comparable
-
-        # The Citrus grammar module
-        # @return [Module] Citrus grammar module (e.g., TomlRB::Document)
-        attr_reader :grammar_module
-
-        # The backend this language is for
-        # @return [Symbol]
-        attr_reader :backend
-
-        # @param grammar_module [Module] A Citrus grammar module with a parse method
-        def initialize(grammar_module)
-          unless grammar_module.respond_to?(:parse)
-            raise TreeHaver::NotAvailable,
-              "Grammar module must respond to :parse. " \
-                "Expected a Citrus grammar module (e.g., TomlRB::Document)."
-          end
-          @grammar_module = grammar_module
-          @backend = :citrus
-        end
-
-        # Get the language name
-        #
-        # Derives a name from the grammar module name.
-        #
-        # @return [Symbol] language name
-        def language_name
-          # Derive name from grammar module (e.g., TomlRB::Document -> :toml)
-          return :unknown unless @grammar_module.respond_to?(:name) && @grammar_module.name
-
-          name = @grammar_module.name.to_s.split("::").first.downcase
-          name.sub(/rb$/, "").to_sym
-        end
-
-        # Alias for language_name (API compatibility)
-        alias_method :name, :language_name
-
-        # Compare languages for equality
-        #
-        # Citrus languages are equal if they have the same backend and grammar_module.
-        # Grammar module uniquely identifies a Citrus language.
-        #
-        # @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
-
-          # Compare by grammar_module name (modules are compared by object_id by default)
-          @grammar_module.name <=> other.grammar_module.name
-        end
-
-        # Hash value for this language (for use in Sets/Hashes)
-        # @return [Integer]
-        def hash
-          [@backend, @grammar_module.name].hash
-        end
-
-        # Alias eql? to ==
-        alias_method :eql?, :==
-
-        # Load language from library path (API compatibility)
-        #
-        # Citrus grammars are Ruby modules, not shared libraries. This method
-        # provides API compatibility with tree-sitter backends by looking up
-        # registered Citrus grammars by name.
-        #
-        # For full API consistency, register a Citrus grammar with:
-        #   TreeHaver.register_language(:toml, grammar_module: TomlRB::Document)
-        #
-        # Then this method will find it when called via `TreeHaver.parser_for(:toml)`.
-        #
-        # @param path [String, nil] Ignored for Citrus (used to derive language name)
-        # @param symbol [String, nil] Used to derive language name if path not provided
-        # @param name [String, Symbol, nil] Language name to look up
-        # @return [Language] Citrus language wrapper
-        # @raise [TreeHaver::NotAvailable] if no Citrus grammar is registered for the language
-        class << self
-          def from_library(path = nil, symbol: nil, name: nil)
-            # Derive language name from path, symbol, or explicit name
-            lang_name = name&.to_sym ||
-              symbol&.to_s&.sub(/^tree_sitter_/, "")&.to_sym ||
-              path && TreeHaver::LibraryPathUtils.derive_language_name_from_path(path)&.to_sym
-
-            unless lang_name
-              raise TreeHaver::NotAvailable,
-                "Citrus backend requires a language name. " \
-                  "Provide name: parameter or register a grammar with TreeHaver.register_language."
-            end
-
-            # Look up registered Citrus grammar
-            registration = TreeHaver::LanguageRegistry.registered(lang_name, :citrus)
-
-            unless registration
-              raise TreeHaver::NotAvailable,
-                "No Citrus grammar registered for #{lang_name.inspect}. " \
-                  "Register one with: TreeHaver.register_language(:#{lang_name}, grammar_module: YourGrammar)"
-            end
-
-            grammar_module = registration[:grammar_module]
-            new(grammar_module)
-          end
-
-          alias_method :from_path, :from_library
-        end
-      end
-
-      # Citrus parser wrapper
-      #
-      # Wraps Citrus grammar modules to provide a tree-sitter-like API.
-      class Parser
-        # Create a new Citrus parser instance
-        #
-        # @raise [TreeHaver::NotAvailable] if citrus gem is not available
-        def initialize
-          raise TreeHaver::NotAvailable, "citrus gem not available" unless Citrus.available?
-          @grammar = nil
-        end
-
-        # Set the grammar for this parser
-        #
-        # Accepts either a Citrus::Language wrapper or a raw Citrus grammar module.
-        # When passed a Language wrapper, extracts the grammar_module from it.
-        # When passed a raw grammar module, uses it directly.
-        #
-        # This flexibility allows both patterns:
-        #   parser.language = TreeHaver::Backends::Citrus::Language.new(TomlRB::Document)
-        #   parser.language = TomlRB::Document  # Also works
-        #
-        # @param grammar [Language, Module] Citrus Language wrapper or grammar module
-        # @return [void]
-        def language=(grammar)
-          # Accept Language wrapper or raw grammar module
-          actual_grammar = case grammar
-          when Language
-            grammar.grammar_module
-          else
-            grammar
-          end
-
-          unless actual_grammar.respond_to?(:parse)
-            raise ArgumentError,
-              "Expected Citrus grammar module with parse method or Language wrapper, " \
-                "got #{grammar.class}"
-          end
-          @grammar = actual_grammar
-        end
-
-        # Parse source code
-        #
-        # @param source [String] the source code to parse
-        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
-        # @raise [TreeHaver::NotAvailable] if no grammar is set
-        # @raise [::Citrus::ParseError] if parsing fails
-        def parse(source)
-          raise TreeHaver::NotAvailable, "No grammar loaded" unless @grammar
-
-          begin
-            citrus_match = @grammar.parse(source)
-            # Return raw Citrus::Tree - TreeHaver::Parser will wrap it
-            Tree.new(citrus_match, source)
-          rescue ::Citrus::ParseError => e
-            # Re-raise with more context
-            raise TreeHaver::Error, "Parse error: #{e.message}"
-          end
-        end
-
-        # Parse source code (compatibility with tree-sitter API)
-        #
-        # Citrus 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 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)  # Citrus doesn't support incremental parsing
-        end
-      end
-
-      # Citrus tree wrapper
-      #
-      # Wraps a Citrus::Match (which represents the parse tree) to provide
-      # tree-sitter-compatible API.
-      #
-      # Inherits from Base::Tree to get shared methods like #errors, #warnings,
-      # #comments, #has_error?, and #inspect.
-      #
-      # @api private
-      class Tree < TreeHaver::Base::Tree
-        # The raw Citrus::Match root
-        # @return [Citrus::Match] The root match
-        attr_reader :root_match
-
-        def initialize(root_match, source)
-          @root_match = root_match
-          super(root_match, source: source)
-        end
-
-        def root_node
-          Node.new(@root_match, @source)
-        end
-      end
-
-      # Citrus node wrapper
-      #
-      # Wraps Citrus::Match objects to provide tree-sitter-compatible node API.
-      #
-      # Citrus::Match provides:
-      # - events[0]: rule name (Symbol) - used as type
-      # - offset: byte position
-      # - length: byte length
-      # - string: matched text
-      # - matches: child matches
-      # - captures: named groups
-      #
-      # Inherits from Base::Node to get shared methods like #first_child, #last_child,
-      # #to_s, #inspect, #==, #<=>, #source_position, #start_line, #end_line, etc.
-      #
-      # Language-specific helpers can be mixed in for convenience:
-      #   require "tree_haver/backends/citrus/toml_helpers"
-      #   TreeHaver::Backends::Citrus::Node.include(TreeHaver::Backends::Citrus::TomlHelpers)
-      #
-      # @api private
-      class Node < TreeHaver::Base::Node
-        attr_reader :match
-
-        def initialize(match, source)
-          @match = match
-          super(match, source: source)
-        end
-
-        # -- Required API Methods (from Base::Node) ----------------------------
-
-        # Get node type from Citrus rule name
-        #
-        # Uses Citrus grammar introspection to dynamically determine node types.
-        # Works with any Citrus grammar without language-specific knowledge.
-        #
-        # Strategy:
-        # 1. Check if first event has a .name method (returns Symbol) - use that
-        # 2. If first event is a Symbol directly - use that
-        # 3. For compound rules (Repeat, Choice), recurse into first match
-        #
-        # @return [String] rule name from grammar
-        def type
-          return "unknown" unless @match.respond_to?(:events)
-          return "unknown" unless @match.events.is_a?(Array)
-          return "unknown" if @match.events.empty?
-
-          extract_type_from_event(@match.events.first)
-        end
-
-        def start_byte
-          @match.offset
-        end
-
-        def end_byte
-          @match.offset + @match.length
-        end
-
-        def children
-          return [] unless @match.respond_to?(:matches)
-          @match.matches.map { |m| Node.new(m, @source) }
-        end
-
-        # -- Overridden Methods ------------------------------------------------
-
-        # Override start_point to calculate from source
-        def start_point
-          calculate_point(@match.offset)
-        end
-
-        # Override end_point to calculate from source
-        def end_point
-          calculate_point(@match.offset + @match.length)
-        end
-
-        # Override text to use Citrus match string
-        def text
-          @match.string
-        end
-
-        # Override child_count for efficiency (avoid building full children array)
-        def child_count
-          @match.respond_to?(:matches) ? @match.matches.size : 0
-        end
-
-        # Override child to handle negative indices properly
-        def child(index)
-          return if index.negative?
-          return unless @match.respond_to?(:matches)
-          return if index >= @match.matches.size
-
-          Node.new(@match.matches[index], @source)
-        end
-
-        # Check if this node represents a structural element vs a terminal/token
-        #
-        # Uses Citrus grammar's terminal? method to determine if this is
-        # a structural rule (like "table", "keyvalue") vs a terminal token
-        # (like "[", "=", whitespace).
-        #
-        # @return [Boolean] true if this is a structural (non-terminal) node
-        def structural?
-          return false unless @match.respond_to?(:events)
-          return false if @match.events.empty?
-
-          first_event = @match.events.first
-
-          # Check if event has terminal? method (Citrus rule object)
-          if first_event.respond_to?(:terminal?)
-            return !first_event.terminal?
-          end
-
-          # For Symbol events, try to look up in grammar
-          if first_event.is_a?(Symbol) && @match.respond_to?(:grammar)
-            grammar = @match.grammar
-            if grammar.respond_to?(:rules) && grammar.rules.key?(first_event)
-              rule = grammar.rules[first_event]
-              return !rule.terminal? if rule.respond_to?(:terminal?)
-            end
-          end
-
-          # Default: assume structural if not a simple string/regex terminal
-          true
-        end
-
-        private
-
-        # Extract type name from a Citrus event object
-        #
-        # Handles different event types:
-        # - Objects with .name method (Citrus rule objects) -> use .name
-        # - Symbol -> use directly
-        # - Compound rules (Repeat, Choice) -> check string representation
-        #
-        # @param event [Object] Citrus event object
-        # @return [String] type name
-        def extract_type_from_event(event)
-          # Case 1: Event has .name method (returns Symbol)
-          if event.respond_to?(:name)
-            name = event.name
-            return name.to_s if name.is_a?(Symbol)
-          end
-
-          # Case 2: Event is a Symbol directly (most common for child nodes)
-          return event.to_s if event.is_a?(Symbol)
-
-          # Case 3: Event is a String
-          return event if event.is_a?(String)
-
-          # Case 4: For compound rules (Repeat, Choice), try string parsing first
-          # This avoids recursion issues
-          str = event.to_s
-
-          # Try to extract rule name from string representation
-          # Examples: "table", "(comment | table)*", "space?", etc.
-          if str =~ /^([a-z_][a-z0-9_]*)/i
-            return $1
-          end
-
-          # If we have a pattern like "(rule1 | rule2)*", we can't determine
-          # the type without looking at actual matches, but that causes recursion
-          # So just return a generic type based on the pattern
-          if /^\(.*\)\*$/.match?(str)
-            return "repeat"
-          elsif /^\(.*\)\?$/.match?(str)
-            return "optional"
-          elsif /^.*\|.*$/.match?(str)
-            return "choice"
-          end
-
-          "unknown"
-        end
-
-        def calculate_point(offset)
-          return {row: 0, column: 0} if offset <= 0
-
-          lines_before = @source[0...offset].count("\n")
-          # Find the newline before this offset (or -1 if we're on line 0)
-          line_start = if offset > 0
-            @source.rindex("\n", offset - 1)
-          end
-          line_start ||= -1
-          column = offset - line_start - 1
-          {row: lines_before, column: column}
-        end
-      end
-
-      # Register the availability checker for RSpec dependency tags
-      TreeHaver::BackendRegistry.register_availability_checker(:citrus) do
-        available?
-      end
-    end
-  end
-end