tree_haver 5.0.5 → 7.1.0

data/lib/tree_haver/backends/parslet.rb

@@ -39,17 +39,18 @@ module TreeHaver
       #   end
       class << self
         def available?
-          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          return @loaded if @load_attempted
+
+          @load_attempted = true
           begin
-            require "parslet"
-            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+            require 'parslet'
+            @loaded = true
           rescue LoadError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            @loaded = false
           rescue StandardError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            @loaded = false
           end
-          @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded
         end
 
         # Reset the load state (primarily for testing)
@@ -57,8 +58,8 @@ module TreeHaver
         # @return [void]
         # @api private
         def reset!
-          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @load_attempted = false
+          @loaded = false
         end
 
         # Get capabilities supported by this backend
@@ -66,15 +67,17 @@ module TreeHaver
         # @return [Hash{Symbol => Object}] capability map
         # @example
         #   TreeHaver::Backends::Parslet.capabilities
-        #   # => { backend: :parslet, query: false, bytes_field: true, incremental: false }
+        #   # => { backend: :parslet, query: false, bytes_field: true, incremental: false, comment_support: :none }
         def capabilities
           return {} unless available?
+
           {
             backend: :parslet,
             query: false,          # Parslet doesn't have a query API like tree-sitter
             bytes_field: true,     # Parslet::Slice provides offset and length
             incremental: false,    # Parslet doesn't support incremental parsing
             pure_ruby: true,       # Parslet is pure Ruby (portable)
+            comment_support: :none
           }
         end
       end
@@ -102,8 +105,8 @@ module TreeHaver
         def initialize(grammar_class)
           unless valid_grammar_class?(grammar_class)
             raise TreeHaver::NotAvailable,
-              "Grammar class must be a Parslet::Parser subclass or respond to :new and return a parser with :parse. " \
-                "Expected a Parslet grammar class (e.g., TOML::Parslet)."
+                  'Grammar class must be a Parslet::Parser subclass or respond to :new and return a parser with :parse. ' \
+                    'Expected a Parslet grammar class (e.g., TOML::Parslet).'
           end
           @grammar_class = grammar_class
           @backend = :parslet
@@ -118,12 +121,12 @@ module TreeHaver
           # Derive name from grammar class (e.g., TOML::Parslet -> :toml)
           return :unknown unless @grammar_class.respond_to?(:name) && @grammar_class.name
 
-          name = @grammar_class.name.to_s.split("::").first.downcase
+          name = @grammar_class.name.to_s.split('::').first.downcase
           name.to_sym
         end
 
         # Alias for language_name (API compatibility)
-        alias_method :name, :language_name
+        alias name language_name
 
         # Compare languages for equality
         #
@@ -147,7 +150,7 @@ module TreeHaver
         end
 
         # Alias eql? to ==
-        alias_method :eql?, :==
+        alias eql? ==
 
         # Load language from library path (API compatibility)
         #
@@ -169,13 +172,13 @@ module TreeHaver
           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
+                        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,
-                "Parslet backend requires a language name. " \
-                  "Provide name: parameter or register a grammar with TreeHaver.register_language."
+                    'Parslet backend requires a language name. ' \
+                      'Provide name: parameter or register a grammar with TreeHaver.register_language.'
             end
 
             # Look up registered Parslet grammar
@@ -183,15 +186,15 @@ module TreeHaver
 
             unless registration
               raise TreeHaver::NotAvailable,
-                "No Parslet grammar registered for #{lang_name.inspect}. " \
-                  "Register one with: TreeHaver.register_language(:#{lang_name}, grammar_class: YourGrammar)"
+                    "No Parslet grammar registered for #{lang_name.inspect}. " \
+                      "Register one with: TreeHaver.register_language(:#{lang_name}, grammar_class: YourGrammar)"
             end
 
             grammar_class = registration[:grammar_class]
             new(grammar_class)
           end
 
-          alias_method :from_path, :from_library
+          alias from_path from_library
         end
 
         private
@@ -200,9 +203,7 @@ module TreeHaver
           return false unless klass.respond_to?(:new)
 
           # Check if it's a Parslet::Parser subclass
-          if defined?(::Parslet::Parser)
-            return true if klass < ::Parslet::Parser
-          end
+          return true if defined?(::Parslet::Parser) && (klass < ::Parslet::Parser)
 
           # Fallback: check if it can create an instance that responds to parse
           begin
@@ -222,10 +223,14 @@ module TreeHaver
         #
         # @raise [TreeHaver::NotAvailable] if parslet gem is not available
         def initialize
-          raise TreeHaver::NotAvailable, "parslet gem not available" unless Parslet.available?
+          raise TreeHaver::NotAvailable, 'parslet gem not available' unless Parslet.available?
+
           @grammar = nil
+          @backend = :parslet
         end
 
+        attr_reader :backend
+
         # Set the grammar for this parser
         #
         # Accepts either a Parslet::Language wrapper or a raw Parslet grammar class.
@@ -241,16 +246,16 @@ module TreeHaver
         def language=(grammar)
           # Accept Language wrapper or raw grammar class
           actual_grammar = case grammar
-          when Language
-            grammar.grammar_class
-          else
-            grammar
-          end
+                           when Language
+                             grammar.grammar_class
+                           else
+                             grammar
+                           end
 
           unless actual_grammar.respond_to?(:new)
             raise ArgumentError,
-              "Expected Parslet grammar class with new method or Language wrapper, " \
-                "got #{grammar.class}"
+                  'Expected Parslet grammar class with new method or Language wrapper, ' \
+                    "got #{grammar.class}"
           end
           @grammar = actual_grammar
         end
@@ -262,7 +267,7 @@ module TreeHaver
         # @raise [TreeHaver::NotAvailable] if no grammar is set
         # @raise [::Parslet::ParseFailed] if parsing fails
         def parse(source)
-          raise TreeHaver::NotAvailable, "No grammar loaded" unless @grammar
+          raise TreeHaver::NotAvailable, 'No grammar loaded' unless @grammar
 
           begin
             parser_instance = @grammar.new
@@ -283,7 +288,7 @@ module TreeHaver
         # @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)  # Parslet doesn't support incremental parsing
+          parse(source) # Parslet doesn't support incremental parsing
         end
       end
 
@@ -307,7 +312,7 @@ module TreeHaver
         end
 
         def root_node
-          Node.new(@parslet_result, @source, type: "document")
+          Node.new(@parslet_result, @source, type: 'document')
         end
       end
 
@@ -426,7 +431,7 @@ module TreeHaver
           when String
             @value
           when Hash, Array
-            @source[start_byte...end_byte] || ""
+            @source[start_byte...end_byte] || ''
           else
             @value.to_s
           end
@@ -442,11 +447,13 @@ module TreeHaver
           when Hash
             keys = @value.keys
             return if index >= keys.size
+
             key = keys[index]
             Node.new(@value[key], @source, key: key)
           when Array
             return if index >= @value.size
-            Node.new(@value[index], @source, type: "element")
+
+            Node.new(@value[index], @source, type: 'element')
           end
         end
 
@@ -482,15 +489,13 @@ module TreeHaver
         private
 
         def calculate_point(offset)
-          return {row: 0, column: 0} if offset <= 0
+          return { row: 0, column: 0 } if offset <= 0
 
           lines_before = @source[0...offset].count("\n")
-          line_start = if offset > 0
-            @source.rindex("\n", offset - 1)
-          end
+          line_start = (@source.rindex("\n", offset - 1) if offset > 0)
           line_start ||= -1
           column = offset - line_start - 1
-          {row: lines_before, column: column}
+          { row: lines_before, column: column }
         end
 
         def infer_type(key)
@@ -498,15 +503,15 @@ module TreeHaver
 
           case @value
           when ::Parslet::Slice
-            "slice"
+            'slice'
           when Hash
-            "hash"
+            'hash'
           when Array
-            "array"
+            'array'
           when String
-            "string"
+            'string'
           else
-            "unknown"
+            'unknown'
           end
         end
 

data/lib/tree_haver/backends/prism.rb

@@ -37,19 +37,20 @@ module TreeHaver
       #   end
       class << self
         def available?
-          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          return @loaded if @load_attempted
+
+          @load_attempted = true
           begin
-            require "prism"
-            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+            require 'prism'
+            @loaded = true
           rescue LoadError
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            @loaded = false
           rescue StandardError
-            # :nocov: defensive code - StandardError during require is extremely rare
-            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-            # :nocov:
+            # simplecov:disable defensive code - StandardError during require is extremely rare
+            @loaded = false
+            # simplecov:enable
           end
-          @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded
         end
 
         # Reset the load state (primarily for testing)
@@ -57,8 +58,8 @@ module TreeHaver
         # @return [void]
         # @api private
         def reset!
-          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
-          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @load_attempted = false
+          @loaded = false
         end
 
         # Get capabilities supported by this backend
@@ -66,9 +67,10 @@ module TreeHaver
         # @return [Hash{Symbol => Object}] capability map
         # @example
         #   TreeHaver::Backends::Prism.capabilities
-        #   # => { backend: :prism, query: false, bytes_field: true, incremental: false, ruby_only: true }
+        #   # => { backend: :prism, query: false, bytes_field: true, incremental: false, ruby_only: true, comment_support: :partial }
         def capabilities
           return {} unless available?
+
           {
             backend: :prism,
             query: false,           # Prism doesn't have tree-sitter-style queries (has pattern matching)
@@ -77,6 +79,8 @@ module TreeHaver
             pure_ruby: false,       # Prism has native C extension (but also pure Ruby mode)
             ruby_only: true,        # Prism only parses Ruby source code
             error_tolerant: true,   # Prism has excellent error recovery
+            comment_support: :partial,
+            comment_attachment_hints: true
           }
         end
       end
@@ -96,11 +100,11 @@ module TreeHaver
         def initialize(name = :ruby, options: {})
           super(name, backend: :prism, options: options)
 
-          unless self.name == :ruby
-            raise TreeHaver::NotAvailable,
-              "Prism only supports Ruby parsing. " \
-                "Got language: #{name.inspect}"
-          end
+          return if self.name == :ruby
+
+          raise TreeHaver::NotAvailable,
+                'Prism only supports Ruby parsing. ' \
+                  "Got language: #{name.inspect}"
         end
 
         # Compare languages for equality by options (since name is always :ruby)
@@ -143,14 +147,14 @@ module TreeHaver
 
             unless lang_name == :ruby
               raise TreeHaver::NotAvailable,
-                "Prism backend only supports Ruby, not #{lang_name}. " \
-                  "Use a tree-sitter backend for #{lang_name} support."
+                    "Prism backend only supports Ruby, not #{lang_name}. " \
+                      "Use a tree-sitter backend for #{lang_name} support."
             end
 
             ruby
           end
 
-          alias_method :from_path, :from_library
+          alias from_path from_library
         end
       end
 
@@ -163,7 +167,8 @@ module TreeHaver
         # @raise [TreeHaver::NotAvailable] if prism is not available
         def initialize
           super
-          raise TreeHaver::NotAvailable, "prism not available" unless Prism.available?
+          raise TreeHaver::NotAvailable, 'prism not available' unless TreeHaver::Backends::Prism.available?
+
           @options = {}
         end
 
@@ -185,11 +190,11 @@ module TreeHaver
               @options = {}
             else
               raise ArgumentError,
-                "Prism only supports Ruby parsing. Got: #{lang.inspect}"
+                    "Prism only supports Ruby parsing. Got: #{lang.inspect}"
             end
           else
             raise ArgumentError,
-              "Expected Prism::Language or :ruby, got #{lang.class}"
+                  "Expected Prism::Language or :ruby, got #{lang.class}"
           end
         end
 
@@ -199,7 +204,7 @@ module TreeHaver
         # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         # @raise [TreeHaver::NotAvailable] if no language is set
         def parse(source)
-          raise TreeHaver::NotAvailable, "No language loaded (use parser.language = :ruby)" unless @language
+          raise TreeHaver::NotAvailable, 'No language loaded (use parser.language = :ruby)' unless @language
 
           # Use Prism.parse with options
           prism_result = ::Prism.parse(source, **@options)
@@ -214,7 +219,7 @@ module TreeHaver
         # @param source [String] the Ruby 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)  # Prism doesn't support incremental parsing
+          parse(source) # Prism doesn't support incremental parsing
         end
       end
 
@@ -262,9 +267,14 @@ module TreeHaver
 
         # Get comments from the parse
         #
-        # @return [Array<::Prism::Comment>]
+        # @return [Array<Comment>]
         def comments
-          @parse_result.comments
+          @comments ||= begin
+            hint_map = comment_hint_map
+            @parse_result.comments.map do |comment|
+              Comment.new(comment, source: source, attachment_hint: hint_map[comment.object_id])
+            end
+          end
         end
 
         # Get magic comments (e.g., frozen_string_literal)
@@ -280,6 +290,87 @@ module TreeHaver
         def data_loc
           @parse_result.data_loc
         end
+
+        private
+
+        def comment_hint_map
+          comments = @parse_result.comments
+          lines = source&.lines || []
+
+          comments.each_with_object({}) do |comment, hints|
+            hints[comment.object_id] = classify_comment_hint(comment, lines)
+          end
+        end
+
+        def classify_comment_hint(comment, lines)
+          line = lines[comment.location.start_line - 1].to_s
+          prefix = line[0...comment.location.start_column]
+          return :inline if prefix.match?(/\S/)
+
+          remaining_nonempty = Array(lines[comment.location.end_line..]).reject { |candidate| candidate.strip.empty? }
+          return :trailing if remaining_nonempty.empty? || remaining_nonempty.all? do |candidate|
+            candidate.lstrip.start_with?('#')
+          end
+
+          :leading
+        end
+      end
+
+      # Prism comment wrapper.
+      #
+      # Prism exposes native Ruby comments via Prism::Comment subclasses and
+      # Prism::Location objects. This wrapper normalizes those objects onto a
+      # small parser-facing contract for downstream consumers.
+      class Comment < TreeHaver::Base::Comment
+        def location
+          inner_comment.location
+        end
+
+        def type
+          self.class.comment_type_for(inner_comment.class)
+        end
+
+        def text
+          inner_comment.slice
+        end
+
+        def start_byte
+          location.start_offset
+        end
+
+        def end_byte
+          location.end_offset
+        end
+
+        def start_point
+          {
+            row: location.start_line - 1,
+            column: location.start_column
+          }
+        end
+
+        def end_point
+          {
+            row: location.end_line - 1,
+            column: location.end_column
+          }
+        end
+
+        def style
+          :line
+        end
+
+        def opening_delimiter
+          '#'
+        end
+
+        class << self
+          def comment_type_for(klass)
+            klass.name.split('::').last
+                 .gsub(/([a-z\d])([A-Z])/, '\\1_\\2')
+                 .downcase
+          end
+        end
       end
 
       # Prism node wrapper
@@ -305,11 +396,11 @@ module TreeHaver
         #
         # @return [String] node type in snake_case
         def type
-          return "nil" if inner_node.nil?
+          return 'nil' if inner_node.nil?
 
           # Convert class name to snake_case type
-          class_name = inner_node.class.name.split("::").last
-          class_name.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, "")
+          class_name = inner_node.class.name.split('::').last
+          class_name.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')
         end
 
         # Alias for type (API compatibility)
@@ -323,6 +414,7 @@ module TreeHaver
         # @return [Integer]
         def start_byte
           return 0 if inner_node.nil? || !inner_node.respond_to?(:location)
+
           loc = inner_node.location
           loc&.start_offset || 0
         end
@@ -332,6 +424,7 @@ module TreeHaver
         # @return [Integer]
         def end_byte
           return 0 if inner_node.nil? || !inner_node.respond_to?(:location)
+
           loc = inner_node.location
           loc&.end_offset || 0
         end
@@ -340,22 +433,24 @@ module TreeHaver
         #
         # @return [Hash{Symbol => Integer}]
         def start_point
-          return {row: 0, column: 0} if inner_node.nil? || !inner_node.respond_to?(:location)
+          return { row: 0, column: 0 } if inner_node.nil? || !inner_node.respond_to?(:location)
+
           loc = inner_node.location
-          return {row: 0, column: 0} unless loc
+          return { row: 0, column: 0 } unless loc
 
-          {row: (loc.start_line - 1), column: loc.start_column}
+          { row: (loc.start_line - 1), column: loc.start_column }
         end
 
         # Get the end position as row/column (0-based)
         #
         # @return [Hash{Symbol => Integer}]
         def end_point
-          return {row: 0, column: 0} if inner_node.nil? || !inner_node.respond_to?(:location)
+          return { row: 0, column: 0 } if inner_node.nil? || !inner_node.respond_to?(:location)
+
           loc = inner_node.location
-          return {row: 0, column: 0} unless loc
+          return { row: 0, column: 0 } unless loc
 
-          {row: (loc.end_line - 1), column: loc.end_column}
+          { row: (loc.end_line - 1), column: loc.end_column }
         end
 
         # Get all child nodes
@@ -372,7 +467,7 @@ module TreeHaver
         #
         # @return [String]
         def text
-          return "" if inner_node.nil?
+          return '' if inner_node.nil?
 
           if inner_node.respond_to?(:slice)
             inner_node.slice
@@ -382,7 +477,7 @@ module TreeHaver
         end
 
         # Alias for Prism compatibility
-        alias_method :slice, :text
+        alias slice text
 
         # Check if this node has errors
         #
@@ -391,11 +486,12 @@ module TreeHaver
           return false if inner_node.nil?
 
           # Check if this is an error node type
-          return true if type.include?("missing") || type.include?("error")
+          return true if type.include?('missing') || type.include?('error')
 
           # Check children recursively (Prism error nodes are usually children)
           return false unless inner_node.respond_to?(:child_nodes)
-          inner_node.child_nodes.compact.any? { |n| n.class.name.to_s.include?("Missing") }
+
+          inner_node.child_nodes.compact.any? { |n| n.class.name.to_s.include?('Missing') }
         end
 
         # Check if this node is a "missing" node (error recovery)
@@ -403,7 +499,8 @@ module TreeHaver
         # @return [Boolean]
         def missing?
           return false if inner_node.nil?
-          type.include?("missing")
+
+          type.include?('missing')
         end
 
         # Get a child by field name (Prism node accessor)
@@ -423,7 +520,7 @@ module TreeHaver
           result.is_a?(::Prism::Node) ? Node.new(result, source) : nil
         end
 
-        alias_method :field, :child_by_field_name
+        alias field child_by_field_name
 
         # String representation
         #
@@ -439,6 +536,7 @@ module TreeHaver
         # @return [Boolean]
         def respond_to_missing?(method_name, include_private = false)
           return false if inner_node.nil?
+
           inner_node.respond_to?(method_name, include_private) || super
         end
 
@@ -468,4 +566,3 @@ module TreeHaver
     end
   end
 end
-