tree_haver 4.0.4 → 5.0.0

data/lib/tree_haver/backends/citrus.rb

@@ -45,8 +45,10 @@ module TreeHaver
             @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
@@ -108,6 +110,22 @@ module TreeHaver
           @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.
@@ -192,23 +210,31 @@ module TreeHaver
 
         # Set the grammar for this parser
         #
-        # Note: TreeHaver::Parser unwraps language objects before calling this method.
-        # This backend receives the raw Citrus grammar module (unwrapped), not the Language wrapper.
+        # 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.
         #
-        # @param grammar [Module] Citrus grammar module with a parse method
+        # 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]
-        # @example
-        #   require "toml-rb"
-        #   # TreeHaver::Parser unwraps Language.new(TomlRB::Document) to just TomlRB::Document
-        #   parser.language = TomlRB::Document  # Backend receives unwrapped module
         def language=(grammar)
-          # grammar is already unwrapped by TreeHaver::Parser
-          unless grammar.respond_to?(:parse)
+          # 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, " \
+              "Expected Citrus grammar module with parse method or Language wrapper, " \
                 "got #{grammar.class}"
           end
-          @grammar = grammar
+          @grammar = actual_grammar
         end
 
         # Parse source code
@@ -247,13 +273,18 @@ module TreeHaver
       # 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
-        attr_reader :root_match, :source
+      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
-          @source = source
+          super(root_match, source: source)
         end
 
         def root_node
@@ -273,22 +304,24 @@ module TreeHaver
       # - 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
-        include Comparable
-        include Enumerable
-
-        attr_reader :match, :source
+      class Node < TreeHaver::Base::Node
+        attr_reader :match
 
         def initialize(match, source)
           @match = match
-          @source = source
+          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.
@@ -308,6 +341,50 @@ module TreeHaver
           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
@@ -387,99 +464,6 @@ module TreeHaver
           "unknown"
         end
 
-        public
-
-        def start_byte
-          @match.offset
-        end
-
-        def end_byte
-          @match.offset + @match.length
-        end
-
-        def start_point
-          calculate_point(@match.offset)
-        end
-
-        def end_point
-          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
-
-        def child_count
-          @match.respond_to?(:matches) ? @match.matches.size : 0
-        end
-
-        def child(index)
-          return unless @match.respond_to?(:matches)
-          return if index >= @match.matches.size
-
-          Node.new(@match.matches[index], @source)
-        end
-
-        def children
-          return [] unless @match.respond_to?(:matches)
-          @match.matches.map { |m| Node.new(m, @source) }
-        end
-
-        def each(&block)
-          return to_enum(__method__) unless block_given?
-          children.each(&block)
-        end
-
-        def has_error?
-          false  # Citrus raises on parse error, so successful parse has no errors
-        end
-
-        def missing?
-          false  # Citrus doesn't have the concept of missing nodes
-        end
-
-        def named?
-          true  # Citrus matches are typically "named" in tree-sitter terminology
-        end
-
-        private
-
         def calculate_point(offset)
           return {row: 0, column: 0} if offset <= 0
 
@@ -494,7 +478,7 @@ module TreeHaver
         end
       end
 
-      # Register availability checker for RSpec dependency tags
+      # Register the availability checker for RSpec dependency tags
       TreeHaver::BackendRegistry.register_availability_checker(:citrus) do
         available?
       end

data/lib/tree_haver/backends/ffi.rb

@@ -17,18 +17,26 @@ module TreeHaver
     #
     # == Tree/Node Architecture
     #
-    # This backend (like all tree-sitter backends: MRI, Rust, FFI, Java) does NOT
-    # define its own Tree or Node classes. Instead:
+    # This backend defines raw `FFI::Tree` and `FFI::Node` wrapper classes that
+    # provide minimal FFI bindings to the tree-sitter C structs. These are **not**
+    # intended for direct use by application code.
     #
-    # - Parser#parse returns raw FFI-wrapped tree objects
-    # - These are wrapped by `TreeHaver::Tree` (inherits from `Base::Tree`)
-    # - `TreeHaver::Tree#root_node` wraps raw nodes in `TreeHaver::Node`
+    # The wrapping hierarchy is:
+    #   FFI::Tree/Node (raw FFI wrappers) → TreeHaver::Tree/Node → Base::Tree/Node
     #
-    # This differs from pure-Ruby backends (Citrus, Prism, Psych) which define
-    # their own `Backend::X::Tree` and `Backend::X::Node` classes.
+    # When you use `TreeHaver::Parser#parse`:
+    # 1. `FFI::Parser#parse` returns an `FFI::Tree` (raw pointer wrapper)
+    # 2. `TreeHaver::Parser` wraps it in `TreeHaver::Tree` (adds source storage)
+    # 3. `TreeHaver::Tree#root_node` wraps `FFI::Node` in `TreeHaver::Node`
     #
-    # @see TreeHaver::Tree The wrapper class for tree-sitter Tree objects
-    # @see TreeHaver::Node The wrapper class for tree-sitter Node objects
+    # The `TreeHaver::Tree` and `TreeHaver::Node` wrappers provide the full unified
+    # API including `#children`, `#text`, `#source`, `#source_position`, etc.
+    #
+    # This differs from pure-Ruby backends (Citrus, Parslet, Prism, Psych) which
+    # define Tree/Node classes that directly inherit from Base::Tree/Base::Node.
+    #
+    # @see TreeHaver::Tree The wrapper class users should interact with
+    # @see TreeHaver::Node The wrapper class users should interact with
     # @see TreeHaver::Base::Tree Base class documenting the Tree API contract
     # @see TreeHaver::Base::Node Base class documenting the Node API contract
     #
@@ -79,16 +87,20 @@ module TreeHaver
           @loaded = begin # rubocop:disable ThreadSafety/ClassInstanceVariable
             # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
             # which tree-sitter uses extensively (ts_tree_root_node, ts_node_child, etc.)
+            # :nocov: TruffleRuby returns false early - subsequent FFI code paths unreachable on TruffleRuby
             if RUBY_ENGINE == "truffleruby"
               false
+            # :nocov:
             else
               require "ffi"
               true
             end
           rescue LoadError
             false
+            # :nocov: defensive code - StandardError during require is extremely rare
           rescue StandardError
             false
+            # :nocov:
           end
           @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
@@ -236,7 +248,8 @@ module TreeHaver
               ffi_lib(name)
               lib_loaded = true
               break
-            rescue ::FFI::NotFoundError, LoadError => e
+            rescue LoadError => e
+              # Note: FFI::NotFoundError inherits from LoadError, so it's caught here too
               last_error = e
             end
 
@@ -267,6 +280,7 @@ module TreeHaver
             attach_function(:ts_node_type, [:ts_node], :string)
             attach_function(:ts_node_child_count, [:ts_node], :uint32)
             attach_function(:ts_node_child, [:ts_node, :uint32], :ts_node)
+            attach_function(:ts_node_child_by_field_name, [:ts_node, :string, :uint32], :ts_node)
             attach_function(:ts_node_start_byte, [:ts_node], :uint32)
             attach_function(:ts_node_end_byte, [:ts_node], :uint32)
             attach_function(:ts_node_start_point, [:ts_node], :ts_point)
@@ -276,6 +290,21 @@ module TreeHaver
             attach_function(:ts_node_is_missing, [:ts_node], :bool)
             attach_function(:ts_node_has_error, [:ts_node], :bool)
 
+            # Node navigation functions
+            attach_function(:ts_node_parent, [:ts_node], :ts_node)
+            attach_function(:ts_node_next_sibling, [:ts_node], :ts_node)
+            attach_function(:ts_node_prev_sibling, [:ts_node], :ts_node)
+            attach_function(:ts_node_next_named_sibling, [:ts_node], :ts_node)
+            attach_function(:ts_node_prev_named_sibling, [:ts_node], :ts_node)
+            attach_function(:ts_node_named_child, [:ts_node, :uint32], :ts_node)
+            attach_function(:ts_node_named_child_count, [:ts_node], :uint32)
+
+            # Descendant lookup functions
+            attach_function(:ts_node_descendant_for_byte_range, [:ts_node, :uint32, :uint32], :ts_node)
+            attach_function(:ts_node_descendant_for_point_range, [:ts_node, :ts_point, :ts_point], :ts_node)
+            attach_function(:ts_node_named_descendant_for_byte_range, [:ts_node, :uint32, :uint32], :ts_node)
+            attach_function(:ts_node_named_descendant_for_point_range, [:ts_node, :ts_point, :ts_point], :ts_node)
+
             # Only mark as fully loaded after all attach_function calls succeed
             @loaded = true
           end
@@ -354,6 +383,30 @@ module TreeHaver
         # Alias eql? to ==
         alias_method :eql?, :==
 
+        # Get the language name
+        #
+        # Derives a name from the symbol or path.
+        #
+        # @return [Symbol] language name
+        def language_name
+          # Try to derive from symbol (e.g., "tree_sitter_toml" -> :toml)
+          if @symbol
+            name = @symbol.to_s.sub(/^tree_sitter_/, "")
+            return name.to_sym
+          end
+
+          # Try to derive from path (e.g., "/path/to/libtree-sitter-toml.so" -> :toml)
+          if @path
+            name = LibraryPathUtils.derive_language_name_from_path(@path)
+            return name.to_sym if name
+          end
+
+          :unknown
+        end
+
+        # Alias for language_name (API compatibility)
+        alias_method :name, :language_name
+
         # Convert to FFI pointer for passing to native functions
         #
         # @return [FFI::Pointer]
@@ -625,10 +678,37 @@ module TreeHaver
         end
       end
 
-      # FFI-based tree-sitter node
+      # FFI-based tree-sitter node (raw backend node)
+      #
+      # This is a **raw backend node** that wraps a TSNode by-value struct from the
+      # tree-sitter C API. It provides the minimal interface needed for tree-sitter
+      # operations but is NOT intended for direct use by application code.
+      #
+      # == Architecture Note
+      #
+      # Unlike pure-Ruby backends (Citrus, Parslet, Prism, Psych) which define Node
+      # classes that inherit from `TreeHaver::Base::Node`, tree-sitter backends (MRI,
+      # Rust, FFI, Java) define raw wrapper classes that get wrapped by `TreeHaver::Node`.
+      #
+      # The wrapping hierarchy is:
+      #   FFI::Node (this class) → TreeHaver::Node → Base::Node
+      #
+      # When you use `TreeHaver::Parser#parse`, the returned tree's nodes are already
+      # wrapped in `TreeHaver::Node`, which provides the full unified API including:
+      # - `#children` - Array of child nodes
+      # - `#text` - Extract text from source
+      # - `#first_child`, `#last_child` - Convenience accessors
+      # - `#start_line`, `#end_line` - 1-based line numbers
+      # - `#source_position` - Hash with position info
+      # - `#each`, `#map`, etc. - Enumerable methods
+      # - `#to_s`, `#inspect` - String representations
+      #
+      # This raw class only implements methods that require direct FFI calls to the
+      # tree-sitter C library. The wrapper adds Ruby-level conveniences.
       #
-      # Wraps a TSNode by-value struct. TSNode is passed by value in the
-      # tree-sitter C API, so we store the struct value directly.
+      # @api private
+      # @see TreeHaver::Node The wrapper class users should interact with
+      # @see TreeHaver::Base::Node The base class documenting the full Node API
       class Node
         include Enumerable
 
@@ -663,6 +743,25 @@ module TreeHaver
           Node.new(child_node)
         end
 
+        # Get a child node by field name
+        #
+        # Tree-sitter grammars define named fields for certain child positions.
+        # For example, in JSON, a "pair" node has "key" and "value" fields.
+        #
+        # @param field_name [String] the field name to look up
+        # @return [Node, nil] the child node, or nil if no child has that field
+        # @example Get the key from a JSON pair
+        #   pair.child_by_field_name("key") #=> Node (type: "string")
+        #   pair.child_by_field_name("value") #=> Node (type: "string" or "number", etc.)
+        def child_by_field_name(field_name)
+          name = String(field_name)
+          child_node = Native.ts_node_child_by_field_name(@val, name, name.bytesize)
+          # ts_node_child_by_field_name returns a null node if field not found
+          return if Native.ts_node_is_null(child_node)
+
+          Node.new(child_node)
+        end
+
         # Get start byte offset
         #
         # @return [Integer]
@@ -718,6 +817,150 @@ module TreeHaver
           !!Native.ts_node_is_missing(@val)
         end
 
+        # Check if this is a named node
+        #
+        # Named nodes represent syntactic constructs (e.g., "pair", "object").
+        # Anonymous nodes represent syntax/punctuation (e.g., "{", ",").
+        #
+        # @return [Boolean] true if this is a named node
+        def named?
+          !!Native.ts_node_is_named(@val)
+        end
+
+        # Get the parent node
+        #
+        # @return [Node, nil] parent node or nil if this is the root
+        def parent
+          parent_node = Native.ts_node_parent(@val)
+          return if Native.ts_node_is_null(parent_node)
+
+          Node.new(parent_node)
+        end
+
+        # Get the next sibling node
+        #
+        # @return [Node, nil] next sibling or nil if none
+        def next_sibling
+          sibling = Native.ts_node_next_sibling(@val)
+          return if Native.ts_node_is_null(sibling)
+
+          Node.new(sibling)
+        end
+
+        # Get the previous sibling node
+        #
+        # @return [Node, nil] previous sibling or nil if none
+        def prev_sibling
+          sibling = Native.ts_node_prev_sibling(@val)
+          return if Native.ts_node_is_null(sibling)
+
+          Node.new(sibling)
+        end
+
+        # Get the next named sibling node
+        #
+        # @return [Node, nil] next named sibling or nil if none
+        def next_named_sibling
+          sibling = Native.ts_node_next_named_sibling(@val)
+          return if Native.ts_node_is_null(sibling)
+
+          Node.new(sibling)
+        end
+
+        # Get the previous named sibling node
+        #
+        # @return [Node, nil] previous named sibling or nil if none
+        def prev_named_sibling
+          sibling = Native.ts_node_prev_named_sibling(@val)
+          return if Native.ts_node_is_null(sibling)
+
+          Node.new(sibling)
+        end
+
+        # Get a named child by index
+        #
+        # @param index [Integer] named child index (0-based)
+        # @return [Node, nil] named child or nil if index out of bounds
+        def named_child(index)
+          return if index < 0 || index >= named_child_count
+
+          child_node = Native.ts_node_named_child(@val, index)
+          return if Native.ts_node_is_null(child_node)
+
+          Node.new(child_node)
+        end
+
+        # Get the count of named children
+        #
+        # @return [Integer] number of named children
+        def named_child_count
+          Native.ts_node_named_child_count(@val)
+        end
+
+        # Find the smallest descendant that spans the given byte range
+        #
+        # @param start_byte [Integer] start byte offset
+        # @param end_byte [Integer] end byte offset
+        # @return [Node, nil] descendant node or nil if not found
+        def descendant_for_byte_range(start_byte, end_byte)
+          node = Native.ts_node_descendant_for_byte_range(@val, start_byte, end_byte)
+          return if Native.ts_node_is_null(node)
+
+          Node.new(node)
+        end
+
+        # Find the smallest named descendant that spans the given byte range
+        #
+        # @param start_byte [Integer] start byte offset
+        # @param end_byte [Integer] end byte offset
+        # @return [Node, nil] named descendant node or nil if not found
+        def named_descendant_for_byte_range(start_byte, end_byte)
+          node = Native.ts_node_named_descendant_for_byte_range(@val, start_byte, end_byte)
+          return if Native.ts_node_is_null(node)
+
+          Node.new(node)
+        end
+
+        # Find the smallest descendant that spans the given point range
+        #
+        # @param start_point [TreeHaver::Point, Hash] start point with :row and :column
+        # @param end_point [TreeHaver::Point, Hash] end point with :row and :column
+        # @return [Node, nil] descendant node or nil if not found
+        def descendant_for_point_range(start_point, end_point)
+          start_pt = Native::TSPoint.new
+          start_pt[:row] = start_point.respond_to?(:row) ? start_point.row : start_point[:row]
+          start_pt[:column] = start_point.respond_to?(:column) ? start_point.column : start_point[:column]
+
+          end_pt = Native::TSPoint.new
+          end_pt[:row] = end_point.respond_to?(:row) ? end_point.row : end_point[:row]
+          end_pt[:column] = end_point.respond_to?(:column) ? end_point.column : end_point[:column]
+
+          node = Native.ts_node_descendant_for_point_range(@val, start_pt, end_pt)
+          return if Native.ts_node_is_null(node)
+
+          Node.new(node)
+        end
+
+        # Find the smallest named descendant that spans the given point range
+        #
+        # @param start_point [TreeHaver::Point, Hash] start point with :row and :column
+        # @param end_point [TreeHaver::Point, Hash] end point with :row and :column
+        # @return [Node, nil] named descendant node or nil if not found
+        def named_descendant_for_point_range(start_point, end_point)
+          start_pt = Native::TSPoint.new
+          start_pt[:row] = start_point.respond_to?(:row) ? start_point.row : start_point[:row]
+          start_pt[:column] = start_point.respond_to?(:column) ? start_point.column : start_point[:column]
+
+          end_pt = Native::TSPoint.new
+          end_pt[:row] = end_point.respond_to?(:row) ? end_point.row : end_point[:row]
+          end_pt[:column] = end_point.respond_to?(:column) ? end_point.column : end_point[:column]
+
+          node = Native.ts_node_named_descendant_for_point_range(@val, start_pt, end_pt)
+          return if Native.ts_node_is_null(node)
+
+          Node.new(node)
+        end
+
         # Iterate over child nodes
         #
         # @yieldparam child [Node] each child node
@@ -757,7 +1000,7 @@ module TreeHaver
         end
       end
 
-      # Register availability checker for RSpec dependency tags
+      # Register the availability checker for RSpec dependency tags
       TreeHaver::BackendRegistry.register_availability_checker(:ffi) do
         available?
       end