markly-merge 1.0.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/markly/merge/backend.rb

@@ -0,0 +1,422 @@
+# frozen_string_literal: true
+
+module Markly
+  module Merge
+    # 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 = Markly::Merge::Backend::Language.markdown(
+    #     flags: Markly::DEFAULT,
+    #     extensions: [:table, :strikethrough]
+    #   )
+    #   tree = parser.parse(markdown_source)
+    #   root = tree.root_node
+    #   puts root.type  # => "document"
+    module Backend
+      @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+      @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+      # Check if the Markly backend is available
+      #
+      # @return [Boolean] true if markly gem is available
+      class << self
+        def available?
+          return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          begin
+            require "markly"
+            @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+          rescue LoadError
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          rescue StandardError
+            @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          end
+          @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
+        end
+
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+        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 = Markly::Merge::Backend::Language.markdown(
+      #     flags: Markly::DEFAULT | Markly::FOOTNOTES,
+      #     extensions: [:table, :strikethrough]
+      #   )
+      #   parser.language = language
+      class Language < ::TreeHaver::Base::Language
+        # 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])
+        # @param options [Hash] parsing options (reserved for future use)
+        def initialize(name = :markdown, flags: nil, extensions: [:table], options: {})
+          super(name, backend: :markly, options: options.merge({flags: flags, extensions: extensions}))
+          @flags = flags  # Will use Markly::DEFAULT if nil at parse time
+          @extensions = extensions
+
+          unless @name == :markdown
+            raise TreeHaver::NotAvailable,
+              "Markly backend only supports Markdown parsing. " \
+                "Got language: #{name.inspect}"
+          end
+        end
+
+        class << self
+          # Create a Markdown language instance
+          #
+          # @param flags [Integer] Markly parse flags
+          # @param extensions [Array<Symbol>] Extensions to enable
+          # @param options [Hash] parsing options (reserved for future use)
+          # @return [Language] Markdown language
+          def markdown(flags: nil, extensions: [:table], options: {})
+            new(:markdown, flags: flags, extensions: extensions, options: options)
+          end
+
+          # Load language from library path (API compatibility)
+          #
+          # @param _path [String] Ignored - Markly doesn't load external grammars
+          # @param symbol [String, nil] Ignored
+          # @param name [String, nil] Language name hint (defaults to :markdown)
+          # @return [Language] Markdown language
+          # @raise [TreeHaver::NotAvailable] if requested language is not Markdown
+          def from_library(_path = nil, symbol: nil, name: nil)
+            lang_name = name || symbol&.to_s&.sub(/^tree_sitter_/, "")&.to_sym || :markdown
+
+            unless lang_name == :markdown
+              raise TreeHaver::NotAvailable,
+                "Markly backend only supports Markdown, not #{lang_name}. " \
+                  "Use a tree-sitter backend for #{lang_name} support."
+            end
+
+            markdown
+          end
+        end
+      end
+
+      # Markly parser wrapper
+      class Parser < ::TreeHaver::Base::Parser
+        # Create a new RBS parser instance
+        #
+        # @raise [TreeHaver::NotAvailable] if rbs gem is not available
+        def initialize
+          super()
+          raise TreeHaver::NotAvailable, "markly gem not available" unless Backend.available?
+        end
+
+        # Set the language for this parser
+        #
+        # @param lang [Language, Symbol] RBS language (should be :rbs or Language instance)
+        # @return [void]
+        def language=(lang)
+          case lang
+          when Language
+            @language = lang
+          when Symbol, String
+            if lang.to_sym == :markdown
+              @language = Language.markdown
+            else
+              raise ArgumentError,
+                "Markly backend only supports Markdown parsing. Got: #{lang.inspect}"
+            end
+          else
+            raise ArgumentError,
+              "Expected Backend::Language or :markdown, got #{lang.class}"
+          end
+        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
+          Backend.available? or raise "Markly not available"
+
+          flags = language.flags || ::Markly::DEFAULT
+          exts = language.extensions || [:table]
+          doc = ::Markly.parse(source, flags: flags, extensions: exts)
+          Tree.new(doc, source)
+        end
+      end
+
+      # Markly tree wrapper
+      #
+      # Wraps Markly parse results to provide tree-sitter-compatible API.
+      #
+      # @api private
+      class Tree < ::TreeHaver::Base::Tree
+        def initialize(document, source)
+          super(document, source: source)
+        end
+
+        def root_node
+          Node.new(inner_tree, source: source, lines: lines)
+        end
+      end
+
+      # Markly node wrapper
+      #
+      # Wraps Markly::Node to provide TreeHaver::Node-compatible interface.
+      class Node < ::TreeHaver::Base::Node
+        # Type normalization map (Markly → canonical)
+        TYPE_MAP = {
+          header: "heading",
+          hrule: "thematic_break",
+          html: "html_block",
+        }.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
+
+        # Get source position from the inner Markly node
+        #
+        # @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 (normalized)
+        #
+        # @return [String] Node type
+        def type
+          raw = inner_node.type.to_s
+          TYPE_MAP[raw.to_sym]&.to_s || raw
+        end
+
+        # 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
+          if inner_node.respond_to?(:string_content)
+            content = inner_node.string_content.to_s
+            return content unless content.empty?
+          end
+
+          if inner_node.respond_to?(:to_plaintext)
+            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: source, lines: lines)
+            child = begin
+              child.next
+            rescue
+              nil
+            end
+          end
+          result
+        end
+
+        # Position information
+
+        def start_byte
+          pos = inner_source_position
+          calculate_byte_offset(pos[:start_line] - 1, pos[:start_column] - 1)
+        end
+
+        def end_byte
+          pos = inner_source_position
+          calculate_byte_offset(pos[:end_line] - 1, pos[:end_column] - 1)
+        end
+
+        def start_point
+          pos = inner_source_position
+          {row: pos[:start_line] - 1, column: pos[:start_column] - 1}
+        end
+
+        def end_point
+          pos = inner_source_position
+          {row: pos[:end_line] - 1, column: pos[:end_column] - 1}
+        end
+
+        # Convert node to CommonMark/Markdown/HTML/plaintext
+        def to_commonmark
+          inner_node.to_commonmark
+        end
+
+        def to_markdown
+          inner_node.to_markdown
+        end
+
+        def to_plaintext
+          inner_node.to_plaintext
+        end
+
+        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: source, lines: lines) : nil
+        end
+
+        # Get the previous sibling
+        # @return [Node, nil]
+        def prev_sibling
+          sibling = begin
+            inner_node.previous
+          rescue
+            nil
+          end
+          sibling ? Node.new(sibling, source: source, lines: 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: source, lines: lines) : nil
+        end
+      end
+
+      # Alias Point to the base class for compatibility
+      Point = ::TreeHaver::Base::Point
+
+      # Register this backend with TreeHaver
+      ::TreeHaver.register_language(
+        :markdown,
+        backend_type: :markly,
+        backend_module: self,
+        gem_name: "markly",
+      )
+
+      # Register the full tag for RSpec dependency tags with require path
+      # This enables tree_haver to lazily load this gem when checking availability
+      ::TreeHaver::BackendRegistry.register_tag(
+        :markly_backend,
+        category: :backend,
+        backend_name: :markly,
+        require_path: "markly/merge",
+      ) { available? }
+    end
+  end
+end

data/lib/markly/merge/debug_logger.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markly
+  module Merge
+    # Debug logging utility for Markly::Merge operations.
+    #
+    # Extends Ast::Merge::DebugLogger to provide consistent logging
+    # across all merge gems. Logs are controlled via environment variables.
+    #
+    # @example Enable debug logging
+    #   ENV["MARKLY_MERGE_DEBUG"] = "1"
+    #   DebugLogger.debug("Parsing markdown", { file: "README.md" })
+    #
+    # @example Time an operation
+    #   result = DebugLogger.time("parse") { Markly.parse(source) }
+    #
+    # @see Ast::Merge::DebugLogger Base module
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      # Configure for markly-merge
+      self.env_var_name = "MARKLY_MERGE_DEBUG"
+      self.log_prefix = "[markly-merge]"
+    end
+  end
+end

data/lib/markly/merge/file_analysis.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Markly
+  module Merge
+    # File analysis for Markdown files using Markly.
+    #
+    # This is a thin wrapper around Markdown::Merge::FileAnalysis that:
+    # - Forces the :markly backend
+    # - Sets the default freeze token to "markly-merge"
+    # - Exposes markly-specific options (flags, extensions)
+    #
+    # @example Basic usage
+    #   analysis = FileAnalysis.new(markdown_source)
+    #   analysis.statements.each do |node|
+    #     puts "#{node.merge_type}: #{node.type}"
+    #   end
+    #
+    # @example With custom freeze token
+    #   analysis = FileAnalysis.new(source, freeze_token: "my-merge")
+    #
+    # @see Markdown::Merge::FileAnalysis Underlying implementation
+    class FileAnalysis < Markdown::Merge::FileAnalysis
+      # Default freeze token for markly-merge
+      # @return [String]
+      DEFAULT_FREEZE_TOKEN = "markly-merge"
+
+      # Initialize file analysis with Markly backend.
+      #
+      # @param source [String] Markdown source code to analyze
+      # @param freeze_token [String] Token for freeze block markers (default: "markly-merge")
+      # @param signature_generator [Proc, nil] Custom signature generator
+      # @param flags [Integer] Markly parse flags (e.g., Markly::FOOTNOTES | Markly::SMART)
+      # @param extensions [Array<Symbol>] Markly extensions to enable (e.g., [:table, :strikethrough])
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil, flags: ::Markly::DEFAULT, extensions: [:table])
+        super(
+          source,
+          backend: :markly,
+          freeze_token: freeze_token,
+          signature_generator: signature_generator,
+          flags: flags,
+          extensions: extensions,
+        )
+      end
+
+      # Returns the FreezeNode class to use.
+      #
+      # @return [Class] Markly::Merge::FreezeNode
+      def freeze_node_class
+        FreezeNode
+      end
+    end
+  end
+end

data/lib/markly/merge/freeze_node.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Markly
+  module Merge
+    # Represents a frozen block of Markdown content that should be preserved during merges.
+    #
+    # Inherits from Markdown::Merge::FreezeNode which provides the generic
+    # freeze block handling.
+    #
+    # Freeze blocks are marked with HTML comments:
+    #   <!-- markly-merge:freeze -->
+    #   ... frozen content ...
+    #   <!-- markly-merge:unfreeze -->
+    #
+    # @example Basic freeze block
+    #   <!-- markly-merge:freeze -->
+    #   ## Custom Section
+    #   This content will not be modified by merge operations.
+    #   <!-- markly-merge:unfreeze -->
+    #
+    # @example Freeze block with reason
+    #   <!-- markly-merge:freeze Manual TOC -->
+    #   ## Table of Contents
+    #   - [Introduction](#introduction)
+    #   - [Usage](#usage)
+    #   <!-- markly-merge:unfreeze -->
+    #
+    # @see Markdown::Merge::FreezeNode
+    class FreezeNode < Markdown::Merge::FreezeNode
+    end
+  end
+end