tree_haver 2.0.0 → 3.1.0

data/lib/tree_haver/backends/citrus.rb

@@ -86,10 +86,16 @@ module TreeHaver
       #   # 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)
@@ -98,8 +104,33 @@ module TreeHaver
                 "Expected a Citrus grammar module (e.g., TomlRB::Document)."
           end
           @grammar_module = grammar_module
+          @backend = :citrus
+        end
+
+        # 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?, :==
+
         # Not applicable for Citrus (tree-sitter-specific)
         #
         # Citrus grammars are Ruby modules, not shared libraries.
@@ -131,30 +162,29 @@ module TreeHaver
 
         # Set the grammar for this parser
         #
-        # @param grammar [Language, Module] Citrus grammar module or Language wrapper
-        # @return [Language, Module] the grammar that was set
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # This backend receives the raw Citrus grammar module (unwrapped), not the Language wrapper.
+        #
+        # @param grammar [Module] Citrus grammar module with a parse method
+        # @return [void]
         # @example
         #   require "toml-rb"
-        #   parser.language = TomlRB::Document  # Pass module directly
-        #   # or
-        #   parser.language = TreeHaver::Backends::Citrus::Language.new(TomlRB::Document)
+        #   # TreeHaver::Parser unwraps Language.new(TomlRB::Document) to just TomlRB::Document
+        #   parser.language = TomlRB::Document  # Backend receives unwrapped module
         def language=(grammar)
-          @grammar = if grammar.respond_to?(:grammar_module)
-            grammar.grammar_module
-          elsif grammar.respond_to?(:parse)
-            grammar
-          else
+          # grammar is already unwrapped by TreeHaver::Parser
+          unless grammar.respond_to?(:parse)
             raise ArgumentError,
-              "Expected Citrus grammar module or Language wrapper, " \
+              "Expected Citrus grammar module with parse method, " \
                 "got #{grammar.class}"
           end
-          grammar
+          @grammar = grammar
         end
 
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @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)
@@ -162,8 +192,8 @@ module TreeHaver
 
           begin
             citrus_match = @grammar.parse(source)
-            inner_tree = Tree.new(citrus_match, source)
-            TreeHaver::Tree.new(inner_tree, source: 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}"
@@ -176,8 +206,8 @@ module TreeHaver
         #
         # @param old_tree [TreeHaver::Tree, nil] ignored (no incremental parsing support)
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
-        def parse_string(old_tree, source)
+        # @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
@@ -213,6 +243,10 @@ module TreeHaver
       # - matches: child matches
       # - captures: named groups
       #
+      # 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
         attr_reader :match, :source
@@ -224,17 +258,104 @@ module TreeHaver
 
         # 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
-          # Citrus stores the rule name in events[0]
           return "unknown" unless @match.respond_to?(:events)
           return "unknown" unless @match.events.is_a?(Array)
           return "unknown" if @match.events.empty?
 
-          first = @match.events.first
-          first.is_a?(Symbol) ? first.to_s : "unknown"
+          extract_type_from_event(@match.events.first)
         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
+
+        public
+
         def start_byte
           @match.offset
         end
@@ -251,6 +372,42 @@ module TreeHaver
           calculate_point(@match.offset + @match.length)
         end
 
+        # Get the 1-based line number where this node starts
+        #
+        # @return [Integer] 1-based line number
+        def start_line
+          start_point[:row] + 1
+        end
+
+        # Get the 1-based line number where this node ends
+        #
+        # @return [Integer] 1-based line number
+        def end_line
+          end_point[: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
+          child(0)
+        end
+
         def text
           @match.string
         end