tree_haver 4.0.5 → 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
@@ -371,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]
@@ -642,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`.
       #
-      # Wraps a TSNode by-value struct. TSNode is passed by value in the
-      # tree-sitter C API, so we store the struct value directly.
+      # 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.
+      #
+      # @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
 
@@ -937,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

data/lib/tree_haver/backends/java.rb

@@ -17,18 +17,27 @@ 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 at the Ruby level. Instead:
+    # This backend defines Ruby wrapper classes (`Java::Language`, `Java::Parser`,
+    # `Java::Tree`, `Java::Node`) that wrap the raw jtreesitter Java objects via
+    # JRuby's Java interop. These are **raw backend wrappers** not intended for
+    # direct use by application code.
     #
-    # - Parser#parse returns raw Java tree objects (via JRuby interop)
-    # - These are wrapped by `TreeHaver::Tree` (inherits from `Base::Tree`)
-    # - `TreeHaver::Tree#root_node` wraps raw nodes in `TreeHaver::Node`
+    # The wrapping hierarchy is:
+    #   Java::Tree/Node (this backend) → 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. `Java::Parser#parse` returns a `Java::Tree` (wrapper around jtreesitter Tree)
+    # 2. `TreeHaver::Parser` wraps it in `TreeHaver::Tree` (adds source storage)
+    # 3. `TreeHaver::Tree#root_node` wraps `Java::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
     #
@@ -228,8 +237,17 @@ module TreeHaver
         # :nocov:
       end
 
-      # Wrapper for java-tree-sitter Language
+      # Java backend language wrapper (raw backend language)
+      #
+      # This is a **raw backend language** that wraps a jtreesitter Language object
+      # via JRuby's Java interop. It is used to configure the parser for a specific
+      # grammar (e.g., TOML, JSON, etc.).
       #
+      # Unlike `TreeHaver::Language` (which is a module with factory methods), this
+      # class holds the actual loaded language data from a grammar shared library.
+      #
+      # @api private
+      # @see TreeHaver::Language The factory module users should interact with
       # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Language.html
       #
       # :nocov:
@@ -456,8 +474,19 @@ module TreeHaver
         end
       end
 
-      # Wrapper for java-tree-sitter Parser
+      # Java backend parser wrapper (raw backend parser)
+      #
+      # This is a **raw backend parser** that wraps a jtreesitter Parser object via
+      # JRuby's Java interop. It is NOT intended for direct use by application code.
       #
+      # Users should use `TreeHaver::Parser` which wraps this class and provides:
+      # - Automatic backend selection
+      # - Language wrapper unwrapping
+      # - Tree wrapping with source storage
+      # - Unified API across all backends
+      #
+      # @api private
+      # @see TreeHaver::Parser The wrapper class users should interact with
       # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Parser.html
       class Parser
         # Create a new parser instance
@@ -543,8 +572,35 @@ module TreeHaver
         end
       end
 
-      # Wrapper for java-tree-sitter Tree
+      # Java backend tree wrapper (raw backend tree)
+      #
+      # This is a **raw backend tree** that wraps a jtreesitter Tree object via
+      # JRuby's Java interop. It is NOT intended for direct use by application code.
+      #
+      # == Architecture Note
+      #
+      # Unlike pure-Ruby backends (Citrus, Parslet, Prism, Psych) which define Tree
+      # classes that inherit from `TreeHaver::Base::Tree`, tree-sitter backends (MRI,
+      # Rust, FFI, Java) define raw wrapper classes that get wrapped by `TreeHaver::Tree`.
       #
+      # The wrapping hierarchy is:
+      #   Java::Tree (this class) → TreeHaver::Tree → Base::Tree
+      #
+      # When you use `TreeHaver::Parser#parse`, the returned tree is already wrapped
+      # in `TreeHaver::Tree`, which provides the full unified API including:
+      # - `#source` - The original source text
+      # - `#root_node` - Returns a `TreeHaver::Node` (not raw `Java::Node`)
+      # - `#errors`, `#warnings`, `#comments` - Parse diagnostics
+      # - `#edit` - Mark tree as edited for incremental parsing
+      # - `#to_s`, `#inspect` - String representations
+      #
+      # This raw class only implements methods that require direct calls to jtreesitter.
+      # The wrapper adds Ruby-level conveniences and stores the source text needed for
+      # `Node#text` extraction.
+      #
+      # @api private
+      # @see TreeHaver::Tree The wrapper class users should interact with
+      # @see TreeHaver::Base::Tree The base class documenting the full Tree API
       # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Tree.html
       class Tree
         attr_reader :impl
@@ -601,8 +657,37 @@ module TreeHaver
         end
       end
 
-      # Wrapper for java-tree-sitter Node
+      # Java backend node wrapper (raw backend node)
+      #
+      # This is a **raw backend node** that wraps a jtreesitter Node object via
+      # JRuby's Java interop. 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:
+      #   Java::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 calls to jtreesitter.
+      # The wrapper adds Ruby-level conveniences.
+      #
+      # @api private
+      # @see TreeHaver::Node The wrapper class users should interact with
+      # @see TreeHaver::Base::Node The base class documenting the full Node API
       # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Node.html
       class Node
         attr_reader :impl
@@ -799,7 +884,7 @@ module TreeHaver
       end
       # :nocov:
 
-      # Register availability checker for RSpec dependency tags
+      # Register the availability checker for RSpec dependency tags
       TreeHaver::BackendRegistry.register_availability_checker(:java) do
         available?
       end

data/lib/tree_haver/backends/mri.rb

@@ -142,6 +142,30 @@ module TreeHaver
           @symbol = symbol
         end
 
+        # 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
+
         # Compare languages for equality
         #
         # MRI languages are equal if they have the same backend, path, and symbol.
@@ -329,7 +353,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(:mri) do
         available?
       end