tree_haver 5.0.5 → 7.1.0

data/lib/tree_haver/base/comment.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Base class for backend comment wrappers.
+    #
+    # This defines the parser-facing contract for normalized comment wrappers in
+    # TreeHaver. Backends that can expose comment objects should subclass this and
+    # implement text/type/location accessors using their native parser data.
+    class Comment
+      ATTACHMENT_HINTS = %i[leading inline trailing].freeze
+
+      # The underlying backend-specific comment object.
+      # @return [Object]
+      attr_reader :inner_comment
+
+      # The source text used for fallback range extraction.
+      # @return [String, nil]
+      attr_reader :source
+
+      # Optional parser-provided attachment hint.
+      # @return [Symbol, nil]
+      attr_reader :attachment_hint
+
+      def initialize(comment, source: nil, attachment_hint: nil)
+        @inner_comment = comment
+        @source = source
+        @attachment_hint = normalize_attachment_hint(attachment_hint)
+      end
+
+      # Get the normalized comment type.
+      # Examples: "inline_comment", "block_comment".
+      # @return [String]
+      def type
+        raise NotImplementedError, "#{self.class}#type must be implemented"
+      end
+
+      # Get the comment text including delimiters when appropriate.
+      # @return [String]
+      def text
+        raise NotImplementedError, "#{self.class}#text must be implemented"
+      end
+
+      # Get the start byte offset of the comment.
+      # @return [Integer]
+      def start_byte
+        raise NotImplementedError, "#{self.class}#start_byte must be implemented"
+      end
+
+      # Get the end byte offset of the comment.
+      # @return [Integer]
+      def end_byte
+        raise NotImplementedError, "#{self.class}#end_byte must be implemented"
+      end
+
+      # Get the start position (row/column, 0-based).
+      # @return [Hash{Symbol => Integer}]
+      def start_point
+        { row: 0, column: 0 }
+      end
+
+      # Get the end position (row/column, 0-based).
+      # @return [Hash{Symbol => Integer}]
+      def end_point
+        { row: 0, column: 0 }
+      end
+
+      # Get the normalized delimiter style.
+      #
+      # @return [Symbol, nil]
+      def style
+        nil
+      end
+
+      # Get the opening delimiter for the comment, when the backend can provide it.
+      #
+      # Examples:
+      # - `#` for hash comments
+      # - `//` for C-style line comments
+      # - `<!--` for HTML/XML block comments
+      #
+      # @return [String, nil]
+      def opening_delimiter
+        nil
+      end
+
+      # Get the closing delimiter for the comment, when applicable.
+      #
+      # This is typically `nil` for line comments.
+      #
+      # @return [String, nil]
+      def closing_delimiter
+        nil
+      end
+
+      # Get the comment body with outer delimiters removed when possible.
+      #
+      # Backends with richer native comment models should override this when they
+      # can provide a more semantically accurate body than simple delimiter
+      # trimming.
+      #
+      # @return [String]
+      def body_text
+        extract_body_text(text.to_s)
+      end
+
+      # Get a matching-friendly normalized comment body.
+      #
+      # This strips leading and trailing whitespace from {#body_text} while
+      # preserving the raw rendered form in {#text}.
+      #
+      # @return [String]
+      def normalized_text
+        body_text.strip
+      end
+
+      # Get delimiter/body metadata in one normalized hash.
+      #
+      # @return [Hash{Symbol => String, nil}]
+      def delimiter_metadata
+        {
+          opening: opening_delimiter,
+          closing: closing_delimiter,
+          body: body_text
+        }
+      end
+
+      # Whether this comment uses a line-comment style.
+      #
+      # @return [Boolean]
+      def line?
+        style == :line
+      end
+
+      # Whether this comment uses a block-comment style.
+      #
+      # @return [Boolean]
+      def block?
+        style == :block
+      end
+
+      # Whether this comment spans multiple source lines.
+      #
+      # @return [Boolean]
+      def multiline?
+        start_line != end_line
+      end
+
+      # Whether this comment has a parser-provided attachment hint.
+      #
+      # @return [Boolean]
+      def attachment_hint?
+        !attachment_hint.nil?
+      end
+
+      # Whether this comment is hinted as leading its owner.
+      #
+      # @return [Boolean]
+      def leading?
+        attachment_hint == :leading
+      end
+
+      # Whether this comment is hinted as inline with its owner.
+      #
+      # @return [Boolean]
+      def inline?
+        attachment_hint == :inline
+      end
+
+      # Whether this comment is hinted as trailing its owner.
+      #
+      # @return [Boolean]
+      def trailing?
+        attachment_hint == :trailing
+      end
+
+      # Get the 1-based start line.
+      #
+      # @return [Integer]
+      def start_line
+        start_point[:row] + 1
+      end
+
+      # Get the 1-based end line.
+      #
+      # @return [Integer]
+      def end_line
+        end_point[:row] + 1
+      end
+
+      # Get a normalized source-position hash.
+      #
+      # @return [Hash{Symbol => Integer}]
+      def source_position
+        {
+          start_line: start_line,
+          end_line: end_line,
+          start_column: start_point[:column],
+          end_column: end_point[:column]
+        }
+      end
+
+      # Whether this comment starts at the first line of the available source.
+      #
+      # @return [Boolean]
+      def at_file_start?
+        start_line == 1
+      end
+
+      # Whether this comment ends at the final line of the available source.
+      #
+      # @return [Boolean]
+      def at_file_end?
+        return false if source_lines.none?
+
+        end_line >= source_lines.length
+      end
+
+      # Return the contiguous blank source lines immediately before this comment.
+      #
+      # This is parser-facing layout metadata. It does not decide ownership; it
+      # simply exposes spacing adjacent to the comment so merge layers can reason
+      # about floating vs attached behavior without rescanning source text.
+      #
+      # @return [Array<String>]
+      def blank_lines_before
+        return [] if at_file_start?
+
+        line_num = start_line - 1
+        blanks = []
+
+        while line_num >= 1
+          line = source_line(line_num)
+          break unless line && line.strip.empty?
+
+          blanks.unshift(line)
+          line_num -= 1
+        end
+
+        blanks
+      end
+
+      # Return the contiguous blank source lines immediately after this comment.
+      #
+      # @return [Array<String>]
+      def blank_lines_after
+        return [] if at_file_end?
+
+        line_num = end_line + 1
+        blanks = []
+
+        while line_num <= source_lines.length
+          line = source_line(line_num)
+          break unless line && line.strip.empty?
+
+          blanks << line
+          line_num += 1
+        end
+
+        blanks
+      end
+
+      # Return the count of immediately preceding blank source lines.
+      #
+      # @return [Integer]
+      def blank_line_count_before
+        blank_lines_before.length
+      end
+
+      # Return the count of immediately following blank source lines.
+      #
+      # @return [Integer]
+      def blank_line_count_after
+        blank_lines_after.length
+      end
+
+      def inspect
+        "#<#{self.class} type=#{type.inspect} range=#{start_byte}...#{end_byte}>"
+      end
+
+      private
+
+      def source_lines
+        @source_lines ||= begin
+          values = source.to_s.split("\n", -1)
+          values.pop if values.last&.empty? && source.to_s.end_with?("\n")
+          values
+        end
+      end
+
+      def source_line(line_number)
+        return if line_number < 1 || line_number > source_lines.length
+
+        source_lines[line_number - 1]
+      end
+
+      def extract_body_text(raw_text)
+        text_without_opening = if opening_delimiter
+                                 raw_text.sub(/\A#{Regexp.escape(opening_delimiter)}[ \t]?/, '')
+                               else
+                                 raw_text
+                               end
+
+        return text_without_opening unless closing_delimiter
+
+        text_without_opening.sub(/[ \t]*#{Regexp.escape(closing_delimiter)}\z/m, '')
+      end
+
+      def normalize_attachment_hint(hint)
+        return if hint.nil?
+
+        normalized = hint.to_sym
+        return normalized if ATTACHMENT_HINTS.include?(normalized)
+
+        raise ArgumentError,
+              "Unknown comment attachment hint: #{hint.inspect}. Expected one of: #{ATTACHMENT_HINTS.join(', ')}"
+      end
+    end
+  end
+end

data/lib/tree_haver/base/language.rb

@@ -36,7 +36,7 @@ module TreeHaver
       end
 
       # Alias for name (tree-sitter compatibility)
-      alias_method :language_name, :name
+      alias language_name name
 
       # -- Shared Implementation ------------------------------------------------
 
@@ -68,7 +68,7 @@ module TreeHaver
       # Human-readable representation
       # @return [String]
       def inspect
-        opts = options.empty? ? "" : " options=#{options}"
+        opts = options.empty? ? '' : " options=#{options}"
         class_name = self.class.name || "#{self.class.superclass.name}(anonymous)"
         "#<#{class_name} name=#{name} backend=#{backend}#{opts}>"
       end

data/lib/tree_haver/base/node.rb

@@ -68,6 +68,14 @@ module TreeHaver
         raise NotImplementedError, "#{self.class}#type must be implemented"
       end
 
+      # The parser's original node type before a backend applies any portable
+      # vocabulary aliases. Backends without aliases use their public type.
+      #
+      # @return [String]
+      def native_type
+        type
+      end
+
       # Get byte offset where the node starts
       # @return [Integer] Start byte offset
       def start_byte
@@ -155,7 +163,7 @@ module TreeHaver
       end
 
       # Alias for named?
-      alias_method :structural?, :named?
+      alias structural? named?
 
       # Check if this node represents a syntax error
       # @return [Boolean] true on error
@@ -172,9 +180,9 @@ module TreeHaver
       # Get the text content of this node
       # @return [String] Node text
       def text
-        return "" unless source
+        return '' unless source
 
-        source[start_byte...end_byte] || ""
+        source[start_byte...end_byte] || ''
       end
 
       # Get a child by field name
@@ -187,13 +195,13 @@ module TreeHaver
       # Get start position (row/col) - 0-based
       # @return [Hash{Symbol => Integer}] {row: 0, column: 0}
       def start_point
-        {row: 0, column: 0}
+        { row: 0, column: 0 }
       end
 
       # Get end position (row/col) - 0-based
       # @return [Hash{Symbol => Integer}] {row: 0, column: 0}
       def end_point
-        {row: 0, column: 0}
+        { row: 0, column: 0 }
       end
 
       # -- Shared Implementation -----------------------------------------------
@@ -215,10 +223,10 @@ module TreeHaver
       def start_line
         sp = start_point
         row = if sp.is_a?(Hash)
-          sp[:row]
-        else
-          (sp.respond_to?(:row) ? sp.row : 0)
-        end
+                sp[:row]
+              else
+                (sp.respond_to?(:row) ? sp.row : 0)
+              end
         row + 1
       end
 
@@ -227,10 +235,10 @@ module TreeHaver
       def end_line
         ep = end_point
         row = if ep.is_a?(Hash)
-          ep[:row]
-        else
-          (ep.respond_to?(:row) ? ep.row : 0)
-        end
+                ep[:row]
+              else
+                (ep.respond_to?(:row) ? ep.row : 0)
+              end
         row + 1
       end
 
@@ -241,31 +249,31 @@ module TreeHaver
         ep = end_point
 
         sp_row = if sp.is_a?(Hash)
-          sp[:row]
-        else
-          (sp.respond_to?(:row) ? sp.row : 0)
-        end
+                   sp[:row]
+                 else
+                   (sp.respond_to?(:row) ? sp.row : 0)
+                 end
         sp_col = if sp.is_a?(Hash)
-          sp[:column]
-        else
-          (sp.respond_to?(:column) ? sp.column : 0)
-        end
+                   sp[:column]
+                 else
+                   (sp.respond_to?(:column) ? sp.column : 0)
+                 end
         ep_row = if ep.is_a?(Hash)
-          ep[:row]
-        else
-          (ep.respond_to?(:row) ? ep.row : 0)
-        end
+                   ep[:row]
+                 else
+                   (ep.respond_to?(:row) ? ep.row : 0)
+                 end
         ep_col = if ep.is_a?(Hash)
-          ep[:column]
-        else
-          (ep.respond_to?(:column) ? ep.column : 0)
-        end
+                   ep[:column]
+                 else
+                   (ep.respond_to?(:column) ? ep.column : 0)
+                 end
 
         {
           start_line: sp_row + 1,
           end_line: ep_row + 1,
           start_column: sp_col,
-          end_column: ep_col,
+          end_column: ep_col
         }
       end
 
@@ -276,7 +284,7 @@ module TreeHaver
         node_type = begin
           type
         rescue NotImplementedError
-          "(not implemented)"
+          '(not implemented)'
         end
         "#<#{class_name} type=#{node_type}>"
       end

data/lib/tree_haver/base/parser.rb

@@ -19,6 +19,10 @@ module TreeHaver
       def parse_string(_old_tree, source)
         parse(source)
       end
+
+      def backend
+        language.respond_to?(:backend) ? language.backend : nil
+      end
     end
   end
 end

data/lib/tree_haver/base/point.rb

@@ -19,9 +19,9 @@ module TreeHaver
       # @return [Integer, nil]
       def [](key)
         case key
-        when :row, "row", 0
+        when :row, 'row', 0
           row
-        when :column, "column", 1
+        when :column, 'column', 1
           column
         end
       end
@@ -29,7 +29,7 @@ module TreeHaver
       # Convert to hash
       # @return [Hash{Symbol => Integer}]
       def to_h
-        {row: row, column: column}
+        { row: row, column: column }
       end
 
       # String representation

data/lib/tree_haver/base/tree.rb

@@ -79,7 +79,7 @@ module TreeHaver
       end
 
       # Get comments from the document
-      # @return [Array] Comments (empty for most pure-Ruby backends)
+      # @return [Array] Backend comment wrappers (empty for most backends)
       def comments
         []
       end

data/lib/tree_haver/citrus_grammar_finder.rb

@@ -67,7 +67,7 @@ module TreeHaver
       return @available if @load_attempted
 
       @load_attempted = true
-      debug = ENV["TREE_HAVER_DEBUG"]
+      debug = ENV['TREE_HAVER_DEBUG']
 
       # Guard against nil require_path (can happen if gem_name was nil)
       if @require_path.nil? || @require_path.empty?
@@ -85,13 +85,13 @@ module TreeHaver
 
         # Verify it responds to parse
         unless @grammar_module.respond_to?(:parse)
-          # :nocov: defensive - requires a gem with malformed grammar module
+          # simplecov:disable defensive - requires a gem with malformed grammar module
           # Show what methods ARE available to help diagnose the issue
           if debug
             available_methods = @grammar_module.methods(false).sort.first(20)
             warn("CitrusGrammarFinder: #{@grammar_const} doesn't respond to :parse")
             warn("CitrusGrammarFinder: #{@grammar_const}.class = #{@grammar_module.class}")
-            warn("CitrusGrammarFinder: #{@grammar_const} is a #{@grammar_module.is_a?(Module) ? "Module" : "non-Module"}")
+            warn("CitrusGrammarFinder: #{@grammar_const} is a #{@grammar_module.is_a?(Module) ? 'Module' : 'non-Module'}")
             warn("CitrusGrammarFinder: Available singleton methods (first 20): #{available_methods.inspect}")
             if @grammar_module.respond_to?(:instance_methods)
               instance_methods = @grammar_module.instance_methods(false).sort.first(20)
@@ -100,49 +100,45 @@ module TreeHaver
           end
           @available = false
           return false
-          # :nocov:
+          # simplecov:enable
         end
 
         @available = true
       rescue LoadError => e
-        # :nocov: defensive - requires gem to not be installed
+        # simplecov:disable defensive - requires gem to not be installed
         # Only show LoadError details when debugging
         if debug
           warn("CitrusGrammarFinder: Failed to load '#{@require_path}': #{e.class}: #{e.message}")
           warn("CitrusGrammarFinder: LoadError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
         end
         @available = false
-        # :nocov:
+        # simplecov:enable
       rescue NameError => e
-        # :nocov: defensive - requires gem with missing constant
+        # simplecov:disable defensive - requires gem with missing constant
         # Only show NameError details when debugging
         if debug
           warn("CitrusGrammarFinder: Failed to resolve '#{@grammar_const}': #{e.class}: #{e.message}")
           warn("CitrusGrammarFinder: NameError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
         end
         @available = false
-        # :nocov:
+        # simplecov:enable
       rescue TypeError => e
-        # :nocov: defensive - TruffleRuby-specific edge case
+        # simplecov:disable defensive - TruffleRuby-specific edge case
         # TruffleRuby's bundled_gems.rb can raise TypeError when File.path is called on nil
         # This happens in bundled_gems.rb:124 warning? method when caller locations return nil
         # Always warn about TypeError as it indicates a platform-specific issue
         warn("CitrusGrammarFinder: TypeError during load of '#{@require_path}': #{e.class}: #{e.message}")
-        warn("CitrusGrammarFinder: This may be a TruffleRuby bundled_gems.rb issue")
-        if debug
-          warn("CitrusGrammarFinder: TypeError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
-        end
+        warn('CitrusGrammarFinder: This may be a TruffleRuby bundled_gems.rb issue')
+        warn("CitrusGrammarFinder: TypeError backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}") if debug
         @available = false
-        # :nocov:
-      rescue => e
-        # :nocov: defensive - catch-all for unexpected errors
+        # simplecov:enable
+      rescue StandardError => e
+        # simplecov:disable defensive - catch-all for unexpected errors
         # Always warn about unexpected errors
         warn("CitrusGrammarFinder: Unexpected error: #{e.class}: #{e.message}")
-        if debug
-          warn("CitrusGrammarFinder: backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}")
-        end
+        warn("CitrusGrammarFinder: backtrace:\n  #{e.backtrace&.first(10)&.join("\n  ")}") if debug
         @available = false
-        # :nocov:
+        # simplecov:enable
       end
 
       @available
@@ -166,16 +162,15 @@ module TreeHaver
     # @raise [NotAvailable] if grammar not available and raise_on_missing is true
     def register!(raise_on_missing: false)
       unless available?
-        if raise_on_missing
-          raise NotAvailable, not_found_message
-        end
+        raise NotAvailable, not_found_message if raise_on_missing
+
         return false
       end
 
       TreeHaver.register_language(
         @language_name,
         grammar_module: @grammar_module,
-        gem_name: @gem_name,
+        gem_name: @gem_name
       )
       true
     end
@@ -190,7 +185,7 @@ module TreeHaver
         grammar_const: @grammar_const,
         require_path: @require_path,
         available: available?,
-        grammar_module: @grammar_module&.name,
+        grammar_module: @grammar_module&.name
       }
     end
 
@@ -210,7 +205,7 @@ module TreeHaver
     # @return [Object] the constant
     # @raise [NameError] if constant not found
     def resolve_constant(const_path)
-      const_path.split("::").reduce(Object) do |mod, const_name|
+      const_path.split('::').reduce(Object) do |mod, const_name|
         mod.const_get(const_name)
       end
     end