tree_haver 2.0.0 → 3.1.0

data/lib/tree_haver/backends/java.rb

@@ -228,13 +228,57 @@ module TreeHaver
       # All Java backend implementation classes require JRuby and cannot be tested on MRI/CRuby.
       # JRuby-specific CI jobs would test this code.
       class Language
+        include Comparable
+
         attr_reader :impl
 
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
+        # The symbol name (if known)
+        # @return [String, nil]
+        attr_reader :symbol
+
         # @api private
-        def initialize(impl)
+        def initialize(impl, path: nil, symbol: nil)
           @impl = impl
+          @backend = :java
+          @path = path
+          @symbol = symbol
+        end
+
+        # Compare languages for equality
+        #
+        # Java languages are equal if they have the same backend, path, and symbol.
+        # Path and symbol uniquely identify a loaded language.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          # Compare by path first, then symbol
+          cmp = (@path || "") <=> (other.path || "")
+          return cmp if cmp.nonzero?
+
+          (@symbol || "") <=> (other.symbol || "")
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @path, @symbol].hash
         end
 
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
         # Load a language from a shared library
         #
         # There are three ways java-tree-sitter can load shared libraries:
@@ -298,7 +342,7 @@ module TreeHaver
               combined_lookup = grammar_lookup.or(Java.runtime_lookup)
 
               java_lang = Java.java_classes[:Language].load(combined_lookup, sym)
-              new(java_lang)
+              new(java_lang, path: path, symbol: symbol)
             rescue ::Java::JavaLang::RuntimeException => e
               cause = e.cause
               root_cause = cause&.cause || cause
@@ -354,7 +398,7 @@ module TreeHaver
               # java-tree-sitter's Language.load(String) searches for the language
               # in the classpath using standard naming conventions
               java_lang = Java.java_classes[:Language].load(name)
-              new(java_lang)
+              new(java_lang, symbol: "tree_sitter_#{name}")
             rescue ::Java::JavaLang::RuntimeException => e
               raise TreeHaver::NotAvailable,
                 "Failed to load language '#{name}': #{e.message}. " \
@@ -383,43 +427,48 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # @param lang [Language] the language to use
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # This backend receives the Language wrapper's inner impl (java Language object).
+        #
+        # @param lang [Object] the Java language object (already unwrapped)
         # @return [void]
         def language=(lang)
-          java_lang = lang.is_a?(Language) ? lang.impl : lang
-          @parser.language = java_lang
+          # lang is already unwrapped by TreeHaver::Parser
+          @parser.language = lang
         end
 
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         def parse(source)
           java_tree = @parser.parse(source)
-          inner_tree = Tree.new(java_tree)
-          TreeHaver::Tree.new(inner_tree, source: source)
+          # Return raw Java::Tree - TreeHaver::Parser will wrap it
+          Tree.new(java_tree)
         end
 
         # Parse source code with optional incremental parsing
         #
+        # Note: old_tree is already unwrapped by TreeHaver::Parser before reaching this method.
+        # The backend receives the raw Tree wrapper's impl, not a TreeHaver::Tree.
+        #
         # When old_tree is provided and has been edited, tree-sitter will reuse
         # unchanged nodes for better performance.
         #
-        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
+        # @param old_tree [Tree, nil] previous backend tree for incremental parsing (already unwrapped)
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Parser.html#parse(io.github.treesitter.jtreesitter.Tree,java.lang.String)
         def parse_string(old_tree, source)
+          # old_tree is already unwrapped to Tree wrapper's impl by TreeHaver::Parser
           if old_tree
-            # Unwrap TreeHaver::Tree to get inner tree
-            inner_old_tree = old_tree.respond_to?(:inner_tree) ? old_tree.inner_tree : old_tree
-            java_old_tree = inner_old_tree.is_a?(Tree) ? inner_old_tree.impl : inner_old_tree
+            java_old_tree = old_tree.is_a?(Tree) ? old_tree.impl : old_tree
             java_tree = @parser.parse(java_old_tree, source)
           else
             java_tree = @parser.parse(source)
           end
-          inner_tree = Tree.new(java_tree)
-          TreeHaver::Tree.new(inner_tree, source: source)
+          # Return raw Java::Tree - TreeHaver::Parser will wrap it
+          Tree.new(java_tree)
         end
       end
 

data/lib/tree_haver/backends/markly.rb

@@ -0,0 +1,559 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  module Backends
+    # Markly backend using the Markly gem (cmark-gfm C library)
+    #
+    # This backend wraps Markly, a Ruby gem that provides bindings to
+    # cmark-gfm, GitHub's fork of the CommonMark C library with extensions.
+    #
+    # @note This backend only parses Markdown source code
+    # @see https://github.com/ioquatix/markly Markly gem
+    #
+    # @example Basic usage
+    #   parser = TreeHaver::Parser.new
+    #   parser.language = TreeHaver::Backends::Markly::Language.markdown(
+    #     flags: Markly::DEFAULT,
+    #     extensions: [:table, :strikethrough]
+    #   )
+    #   tree = parser.parse(markdown_source)
+    #   root = tree.root_node
+    #   puts root.type  # => "document"
+    module Markly
+      @load_attempted = false
+      @loaded = false
+
+      # Check if the Markly backend is available
+      #
+      # @return [Boolean] true if markly gem is available
+      class << self
+        def available?
+          return @loaded if @load_attempted
+          @load_attempted = true
+          begin
+            require "markly"
+            @loaded = true
+          rescue LoadError
+            @loaded = false
+          end
+          @loaded
+        end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false
+          @loaded = false
+        end
+
+        # Get capabilities supported by this backend
+        #
+        # @return [Hash{Symbol => Object}] capability map
+        def capabilities
+          return {} unless available?
+          {
+            backend: :markly,
+            query: false,
+            bytes_field: false,       # Markly uses line/column
+            incremental: false,
+            pure_ruby: false,         # Uses C via FFI
+            markdown_only: true,
+            error_tolerant: true,     # Markdown is forgiving
+            gfm_extensions: true,     # Supports GitHub Flavored Markdown
+          }
+        end
+      end
+
+      # Markly language wrapper
+      #
+      # Markly only parses Markdown. This class exists for API compatibility
+      # and to pass through Markly-specific options (flags, extensions).
+      #
+      # @example
+      #   language = TreeHaver::Backends::Markly::Language.markdown(
+      #     flags: Markly::DEFAULT | Markly::FOOTNOTES,
+      #     extensions: [:table, :strikethrough]
+      #   )
+      #   parser.language = language
+      class Language
+        include Comparable
+
+        # The language name (always :markdown for Markly)
+        # @return [Symbol]
+        attr_reader :name
+
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # Markly parse flags
+        # @return [Integer]
+        attr_reader :flags
+
+        # Markly extensions to enable
+        # @return [Array<Symbol>]
+        attr_reader :extensions
+
+        # Create a new Markly language instance
+        #
+        # @param name [Symbol] Language name (should be :markdown)
+        # @param flags [Integer] Markly parse flags (default: Markly::DEFAULT)
+        # @param extensions [Array<Symbol>] Extensions to enable (default: [:table])
+        def initialize(name = :markdown, flags: nil, extensions: [:table])
+          @name = name.to_sym
+          @backend = :markly
+          @flags = flags  # Will use Markly::DEFAULT if nil at parse time
+          @extensions = extensions
+        end
+
+        class << self
+          # Create a Markdown language instance
+          #
+          # @param flags [Integer] Markly parse flags
+          # @param extensions [Array<Symbol>] Extensions to enable
+          # @return [Language] Markdown language
+          def markdown(flags: nil, extensions: [:table])
+            new(:markdown, flags: flags, extensions: extensions)
+          end
+        end
+
+        # Comparison for sorting/equality
+        def <=>(other)
+          return unless other.is_a?(Language)
+          name <=> other.name
+        end
+
+        def inspect
+          "#<TreeHaver::Backends::Markly::Language name=#{name} flags=#{flags} extensions=#{extensions}>"
+        end
+      end
+
+      # Markly parser wrapper
+      class Parser
+        attr_accessor :language
+
+        def initialize
+          @language = nil
+        end
+
+        # Parse Markdown source code
+        #
+        # @param source [String] Markdown source to parse
+        # @return [Tree] Parsed tree
+        def parse(source)
+          raise "Language not set" unless @language
+          Markly.available? or raise "Markly not available"
+
+          flags = @language.flags || ::Markly::DEFAULT
+          extensions = @language.extensions || [:table]
+          doc = ::Markly.parse(source, flags: flags, extensions: extensions)
+          Tree.new(doc, source)
+        end
+
+        # Alias for compatibility
+        def parse_string(_old_tree, source)
+          parse(source)
+        end
+      end
+
+      # Markly tree wrapper
+      class Tree
+        attr_reader :inner_tree, :source
+
+        def initialize(document, source)
+          @inner_tree = document
+          @source = source
+          @lines = source.lines
+        end
+
+        def root_node
+          Node.new(@inner_tree, @source, @lines)
+        end
+
+        def errors
+          []
+        end
+
+        def warnings
+          []
+        end
+
+        def comments
+          []
+        end
+
+        def inspect
+          "#<TreeHaver::Backends::Markly::Tree>"
+        end
+      end
+
+      # Markly node wrapper
+      #
+      # Wraps Markly::Node to provide TreeHaver::Node-compatible interface.
+      #
+      # Note: Markly uses different type names than Commonmarker:
+      # - :header instead of :heading
+      # - :hrule instead of :thematic_break
+      # - :blockquote instead of :block_quote
+      # - :html instead of :html_block
+      class Node
+        include Comparable
+
+        # Type normalization map (Markly → canonical)
+        TYPE_MAP = {
+          header: "heading",
+          hrule: "thematic_break",
+          html: "html_block",
+          # blockquote is the same
+          # Most types are the same between Markly and Commonmarker
+        }.freeze
+
+        # Default source position for nodes that don't have position info
+        DEFAULT_SOURCE_POSITION = {
+          start_line: 1,
+          start_column: 1,
+          end_line: 1,
+          end_column: 1,
+        }.freeze
+
+        attr_reader :inner_node, :source
+
+        def initialize(node, source, lines = nil)
+          @inner_node = node
+          @source = source
+          @lines = lines || source.lines
+        end
+
+        # Get source position from the inner Markly node
+        #
+        # Markly provides source_position as a hash with :start_line, :start_column,
+        # :end_line, :end_column (all 1-based).
+        #
+        # @return [Hash{Symbol => Integer}] Source position from Markly
+        # @api private
+        def inner_source_position
+          @inner_source_position ||= if @inner_node.respond_to?(:source_position)
+            @inner_node.source_position || DEFAULT_SOURCE_POSITION
+          else
+            DEFAULT_SOURCE_POSITION
+          end
+        end
+
+        # Get the node type as a string
+        #
+        # Normalizes Markly types to canonical names for consistency.
+        #
+        # @return [String] Node type
+        def type
+          raw_type = @inner_node.type.to_s
+          TYPE_MAP[raw_type.to_sym]&.to_s || raw_type
+        end
+
+        alias_method :kind, :type
+
+        # Get the raw (non-normalized) type
+        # @return [String]
+        def raw_type
+          @inner_node.type.to_s
+        end
+
+        # Get the text content of this node
+        #
+        # @return [String] Node text
+        def text
+          # Markly nodes have string_content for leaf nodes
+          if @inner_node.respond_to?(:string_content)
+            @inner_node.string_content.to_s
+          elsif @inner_node.respond_to?(:to_plaintext)
+            # For container nodes, use to_plaintext or concatenate
+            begin
+              @inner_node.to_plaintext
+            rescue
+              children.map(&:text).join
+            end
+          else
+            children.map(&:text).join
+          end
+        end
+
+        # Get child nodes
+        #
+        # Markly uses first_child/next pattern
+        #
+        # @return [Array<Node>] Child nodes
+        def children
+          result = []
+          child = begin
+            @inner_node.first_child
+          rescue
+            nil
+          end
+          while child
+            result << Node.new(child, @source, @lines)
+            child = begin
+              child.next
+            rescue
+              nil
+            end
+          end
+          result
+        end
+
+        def each(&block)
+          return to_enum(__method__) unless block
+          children.each(&block)
+        end
+
+        def child_count
+          children.size
+        end
+
+        def child(index)
+          children[index]
+        end
+
+        # Position information
+        # Markly provides source_position as a hash with :start_line, :start_column, :end_line, :end_column (1-based)
+
+        def start_byte
+          pos = inner_source_position
+          line = pos[:start_line] - 1
+          col = pos[:start_column] - 1
+          calculate_byte_offset(line, col)
+        end
+
+        def end_byte
+          pos = inner_source_position
+          line = pos[:end_line] - 1
+          col = pos[:end_column] - 1
+          calculate_byte_offset(line, col)
+        end
+
+        def start_point
+          pos = inner_source_position
+          line = pos[:start_line] - 1
+          col = pos[:start_column] - 1
+          Point.new(line, col)
+        end
+
+        def end_point
+          pos = inner_source_position
+          line = pos[:end_line] - 1
+          col = pos[:end_column] - 1
+          Point.new(line, col)
+        end
+
+        # Get the 1-based line number where this node starts
+        #
+        # Markly provides 1-based line numbers via source_position hash.
+        #
+        # @return [Integer] 1-based line number
+        def start_line
+          inner_source_position[:start_line]
+        end
+
+        # Get the 1-based line number where this node ends
+        #
+        # @return [Integer] 1-based line number
+        def end_line
+          inner_source_position[:end_line]
+        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
+          children.first
+        end
+
+        def named?
+          true
+        end
+
+        alias_method :structural?, :named?
+
+        def has_error?
+          false
+        end
+
+        def missing?
+          false
+        end
+
+        def <=>(other)
+          return unless other.respond_to?(:start_byte)
+          cmp = start_byte <=> other.start_byte
+          return cmp unless cmp&.zero?
+          end_byte <=> other.end_byte
+        end
+
+        def inspect
+          "#<TreeHaver::Backends::Markly::Node type=#{type} raw_type=#{raw_type}>"
+        end
+
+        # Convert node to CommonMark format
+        #
+        # Delegates to the inner Markly node's to_commonmark method.
+        #
+        # @return [String] CommonMark representation
+        def to_commonmark
+          @inner_node.to_commonmark
+        end
+
+        # Convert node to Markdown format
+        #
+        # Delegates to the inner Markly node's to_markdown method.
+        #
+        # @return [String] Markdown representation
+        def to_markdown
+          @inner_node.to_markdown
+        end
+
+        # Convert node to plain text
+        #
+        # Delegates to the inner Markly node's to_plaintext method.
+        #
+        # @return [String] Plain text representation
+        def to_plaintext
+          @inner_node.to_plaintext
+        end
+
+        # Convert node to HTML
+        #
+        # Delegates to the inner Markly node's to_html method.
+        #
+        # @return [String] HTML representation
+        def to_html
+          @inner_node.to_html
+        end
+
+        # Markly-specific methods
+
+        # Get heading level (1-6)
+        # @return [Integer, nil]
+        def header_level
+          return unless raw_type == "header"
+          begin
+            @inner_node.header_level
+          rescue
+            nil
+          end
+        end
+
+        # Get fence info for code blocks
+        # @return [String, nil]
+        def fence_info
+          return unless type == "code_block"
+          begin
+            @inner_node.fence_info
+          rescue
+            nil
+          end
+        end
+
+        # Get URL for links/images
+        # @return [String, nil]
+        def url
+          @inner_node.url
+        rescue
+          nil
+        end
+
+        # Get title for links/images
+        # @return [String, nil]
+        def title
+          @inner_node.title
+        rescue
+          nil
+        end
+
+        # Get the next sibling (Markly uses .next)
+        # @return [Node, nil]
+        def next_sibling
+          sibling = begin
+            @inner_node.next
+          rescue
+            nil
+          end
+          sibling ? Node.new(sibling, @source, @lines) : nil
+        end
+
+        # Get the previous sibling
+        # @return [Node, nil]
+        def previous_sibling
+          sibling = begin
+            @inner_node.previous
+          rescue
+            nil
+          end
+          sibling ? Node.new(sibling, @source, @lines) : nil
+        end
+
+        # Get the parent node
+        # @return [Node, nil]
+        def parent
+          p = begin
+            @inner_node.parent
+          rescue
+            nil
+          end
+          p ? Node.new(p, @source, @lines) : nil
+        end
+
+        private
+
+        def calculate_byte_offset(line, column)
+          offset = 0
+          @lines.each_with_index do |line_content, idx|
+            if idx < line
+              offset += line_content.bytesize
+            else
+              offset += [column, line_content.bytesize].min
+              break
+            end
+          end
+          offset
+        end
+      end
+
+      # Point struct for position information
+      Point = Struct.new(:row, :column) do
+        def [](key)
+          case key
+          when :row, "row" then row
+          when :column, "column" then column
+          end
+        end
+
+        def to_h
+          {row: row, column: column}
+        end
+
+        def to_s
+          "(#{row}, #{column})"
+        end
+
+        def inspect
+          "#<TreeHaver::Backends::Markly::Point row=#{row} column=#{column}>"
+        end
+      end
+    end
+  end
+end