tree_haver 7.0.0 → 7.1.0

data/lib/tree_haver/backends/tslp.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Backends
+    # TSLP backend using tree_sitter_language_pack's on-demand parser API.
+    #
+    # This backend intentionally requires the real parser API. The language-pack
+    # process API is not a TreeHaver parser backend and must not be used as a
+    # merge-gem integration surface.
+    module Tslp
+      @load_attempted = false
+      @loaded = false
+      @unavailable_reason = nil
+      @language_availability = {}
+      @language_unavailable_reasons = {}
+      PARSER_SMOKE_SOURCES = {
+        'json' => '{}',
+        'json5' => '{}',
+        'bash' => "echo tree_haver\n",
+        'go' => "package main\nfunc main() {}\n",
+        'html' => "<!doctype html>\n<title>TreeHaver</title>\n",
+        'markdown' => "# TreeHaver\n",
+        'ruby' => "class TreeHaverSmoke\nend\n",
+        'rust' => "fn main() {}\n",
+        'typescript' => "export const treeHaver = true;\n",
+        'toml' => "title = \"tree_haver\"\n",
+        'yaml' => "tree_haver: true\n"
+      }.freeze
+      DEFAULT_PARSER_SMOKE_SOURCE = ''
+
+      class << self
+        attr_reader :unavailable_reason
+
+        def available?
+          return @loaded if @load_attempted
+
+          @load_attempted = true
+          begin
+            require 'tree_sitter_language_pack' unless defined?(::TreeSitterLanguagePack)
+            @loaded = parser_api_available?
+            if !@loaded && @unavailable_reason.to_s.empty?
+              @unavailable_reason = 'tree_sitter_language_pack parser API is not exposed'
+            end
+          rescue LoadError => e
+            @loaded = false
+            @unavailable_reason = e.message
+          rescue StandardError => e
+            @loaded = false
+            @unavailable_reason = e.message
+          end
+          @loaded
+        end
+
+        def reset!
+          @load_attempted = false
+          @loaded = false
+          @unavailable_reason = nil
+          @language_availability = {}
+          @language_unavailable_reasons = {}
+        end
+
+        def capabilities
+          return {} unless available?
+
+          {
+            backend: :tslp,
+            query: false,
+            bytes_field: true,
+            incremental: false,
+            comment_support: :nodes_only,
+            language_pack: true
+          }
+        end
+
+        def parser_available_for?(language_name)
+          return false unless available?
+
+          name = language_name.to_s
+          return @language_availability.fetch(name) if @language_availability.key?(name)
+
+          @language_availability[name] = smoke_parse_language(name)
+          @language_unavailable_reasons[name] = @unavailable_reason unless @language_availability.fetch(name)
+          @language_availability.fetch(name)
+        rescue StandardError => e
+          @unavailable_reason = e.message
+          @language_unavailable_reasons[language_name.to_s] = e.message
+          false
+        end
+
+        private
+
+        def parser_api_available?
+          return false unless ::TreeSitterLanguagePack.respond_to?(:get_parser)
+          return false unless defined?(::TreeSitterLanguagePack::Parser)
+          return false unless ::TreeSitterLanguagePack::Parser.instance_methods.include?(:parse)
+
+          parser_api_smoke_test
+        rescue StandardError => e
+          @unavailable_reason = e.message
+          false
+        end
+
+        def parser_api_smoke_test
+          language_name, source = PARSER_SMOKE_SOURCES.find do |name, _smoke_source|
+            !::TreeSitterLanguagePack.respond_to?(:has_language) ||
+              ::TreeSitterLanguagePack.has_language(name)
+          end
+          return false unless language_name
+
+          smoke_parse_language(language_name, source: source)
+        end
+
+        def smoke_parse_language(language_name, source: smoke_source_for(language_name))
+          name = language_name.to_s
+          if ::TreeSitterLanguagePack.respond_to?(:has_language) &&
+             !::TreeSitterLanguagePack.has_language(name)
+            @unavailable_reason = "tree_sitter_language_pack does not publish #{name}"
+            return false
+          end
+
+          parser = ::TreeSitterLanguagePack.get_parser(name)
+          return false unless parser
+
+          tree = parser.parse(source)
+          return false unless tree&.respond_to?(:root_node)
+
+          root = tree.root_node
+          root && !node_has_error?(root)
+        end
+
+        def smoke_source_for(language_name)
+          PARSER_SMOKE_SOURCES.fetch(language_name.to_s, DEFAULT_PARSER_SMOKE_SOURCE)
+        end
+
+        def node_has_error?(node)
+          if node.respond_to?(:has_error)
+            node.has_error
+          elsif node.respond_to?(:has_error?)
+            node.has_error?
+          else
+            false
+          end
+        end
+      end
+
+      class Language < TreeHaver::Base::Language
+        def initialize(name)
+          super(name.to_sym, backend: :tslp, options: {})
+        end
+
+        class << self
+          def from_library(_path = nil, symbol: nil, name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            new(name || :unknown)
+          end
+        end
+      end
+
+      class Parser < TreeHaver::Base::Parser
+        def parse(source)
+          raise TreeHaver::NotAvailable, unavailable_message unless Tslp.available?
+          raise TreeHaver::NotAvailable, 'TSLP language is not set' unless language
+
+          parser = ::TreeSitterLanguagePack.get_parser(language.name.to_s)
+          raise TreeHaver::NotAvailable, "TSLP did not return a parser for #{language.name}" unless parser
+
+          raw_tree = parser.parse(source)
+          raise TreeHaver::NotAvailable, "TSLP did not return a parse tree for #{language.name}" unless raw_tree
+
+          Tree.new(raw_tree, source: source, language: language.name)
+        end
+
+        private
+
+        def unavailable_message
+          reason = Tslp.unavailable_reason
+          detail = reason.to_s.empty? ? 'unknown reason' : reason
+          "tree_sitter_language_pack parser API is unavailable: #{detail}"
+        end
+      end
+
+      class Tree < TreeHaver::Base::Tree
+        attr_reader :language
+
+        def initialize(inner_tree = nil, source: nil, lines: nil, language: nil)
+          super(inner_tree, source: source, lines: lines)
+          @language = language.to_s
+        end
+
+        def root_node
+          Node.new(inner_tree.root_node, source: source, lines: lines, language: language)
+        end
+      end
+
+      class Node < TreeHaver::Base::Node
+        NODE_TYPE_ALIASES = {
+          'json5' => {
+            'file' => 'document',
+            'member' => 'pair'
+          }
+        }.freeze
+
+        attr_reader :language
+
+        def initialize(node, source: nil, lines: nil, language: nil)
+          super(node, source: source, lines: lines)
+          @language = language.to_s
+        end
+
+        def type
+          NODE_TYPE_ALIASES.fetch(language, {}).fetch(native_type, native_type)
+        end
+
+        def native_type
+          inner_node.kind
+        end
+
+        def start_byte
+          inner_node.start_byte
+        end
+
+        def end_byte
+          inner_node.end_byte
+        end
+
+        def start_point
+          point = inner_node.start_position
+          { row: point.row, column: point.column }
+        end
+
+        def end_point
+          point = inner_node.end_position
+          { row: point.row, column: point.column }
+        end
+
+        def children
+          Array.new(inner_node.child_count) do |index|
+            child = inner_node.child(index)
+            child && self.class.new(child, source: source, lines: lines, language: language)
+          end.compact
+        end
+
+        def child_by_field_name(name)
+          child = inner_node.child_by_field_name(name.to_s) if inner_node.respond_to?(:child_by_field_name)
+          child && self.class.new(child, source: source, lines: lines, language: language)
+        end
+
+        def parent
+          parent = inner_node.parent if inner_node.respond_to?(:parent)
+          parent && self.class.new(parent, source: source, lines: lines, language: language)
+        end
+
+        def named?
+          inner_node.is_named
+        end
+
+        def has_error?
+          inner_node.has_error
+        end
+
+        def error?
+          inner_node.is_error
+        end
+
+        def missing?
+          inner_node.is_missing
+        end
+
+        def extra?
+          inner_node.is_extra
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Base
+    # Base class for backend Language implementations
+    #
+    # This class defines the API contract for all language implementations.
+    # Backend-specific Language classes should inherit from this and implement
+    # the required interface.
+    #
+    # @abstract Subclasses must implement #name and #backend at minimum
+    class Language
+      include Comparable
+
+      # The language name (e.g., :markdown, :ruby, :json)
+      # @return [Symbol] Language name
+      attr_reader :name
+
+      # The backend this language is for
+      # @return [Symbol] Backend identifier (e.g., :commonmarker, :markly, :prism)
+      attr_reader :backend
+
+      # Language-specific options
+      # @return [Hash] Options hash
+      attr_reader :options
+
+      # Create a new Language instance
+      #
+      # @param name [Symbol, String] Language name
+      # @param backend [Symbol] Backend identifier
+      # @param options [Hash] Backend-specific options
+      def initialize(name, backend:, options: {})
+        @name = name.to_sym
+        @backend = backend.to_sym
+        @options = options
+      end
+
+      # Alias for name (tree-sitter compatibility)
+      alias language_name name
+
+      # -- Shared Implementation ------------------------------------------------
+
+      # Comparison based on backend then name
+      # @param other [Object]
+      # @return [Integer, nil]
+      def <=>(other)
+        return unless other.is_a?(Language)
+        return unless other.respond_to?(:backend) && other.backend == backend
+
+        name <=> other.name
+      end
+
+      # Hash value for use in Sets/Hashes
+      # @return [Integer]
+      def hash
+        [backend, name, options.to_a.sort].hash
+      end
+
+      # Equality check for Hash keys
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+        return false unless other.is_a?(Language)
+
+        backend == other.backend && name == other.name && options == other.options
+      end
+
+      # Human-readable representation
+      # @return [String]
+      def inspect
+        opts = options.empty? ? '' : " options=#{options}"
+        class_name = self.class.name || "#{self.class.superclass.name}(anonymous)"
+        "#<#{class_name} name=#{name} backend=#{backend}#{opts}>"
+      end
+
+      # -- Class Methods --------------------------------------------------------
+
+      class << self
+        # Load a language from a library path (factory method)
+        #
+        # For pure-Ruby backends (Commonmarker, Markly, Prism, Psych), this
+        # typically ignores the path and returns the single supported language.
+        #
+        # For tree-sitter backends (MRI, Rust, FFI, Java), this loads the
+        # language from the shared library file.
+        #
+        # @param _path [String, nil] Path to shared library (optional for pure-Ruby)
+        # @param symbol [String, nil] Symbol name to load (optional)
+        # @param name [String, nil] Language name hint (optional)
+        # @return [Language] Loaded language instance
+        # @raise [NotImplementedError] If not implemented by subclass
+        def from_library(_path = nil, symbol: nil, name: nil)
+          raise NotImplementedError, "#{self}.from_library must be implemented"
+        end
+      end
+    end
+  end
+end