commonmarker-merge 7.0.0 → 7.1.3

data/lib/commonmarker/merge/backend.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    # Commonmarker backend using the Commonmarker gem (comrak Rust parser)
+    #
+    # This backend wraps Commonmarker, a Ruby gem that provides bindings to
+    # comrak, a fast CommonMark-compliant Markdown parser written in Rust.
+    #
+    # @note This backend only parses Markdown source code
+    # @see https://github.com/gjtorikian/commonmarker Commonmarker gem
+    #
+    # @example Basic usage
+    #   parser = TreeHaver::Parser.new
+    #   parser.language = Commonmarker::Merge::Backend::Language.markdown
+    #   tree = parser.parse(markdown_source)
+    #   root = tree.root_node
+    #   puts root.type  # => "document"
+    module Backend
+      Markdown::Merge::BackendSupport.install!(
+        backend_module: self,
+        backend_name: :commonmarker,
+        gem_name: 'commonmarker',
+        require_path: 'commonmarker/merge'
+      )
+
+      # Commonmarker language wrapper
+      #
+      # Commonmarker only parses Markdown. This class exists for API compatibility.
+      #
+      # @example
+      #   language = Commonmarker::Merge::Backend::Language.markdown
+      #   parser.language = language
+      class Language < TreeHaver::Base::Language
+        # Create a new Commonmarker language instance
+        #
+        # @param name [Symbol] Language name (should be :markdown)
+        # @param options [Hash] Commonmarker parse options
+        def initialize(name = :markdown, options: {})
+          super(name, backend: :commonmarker, options: options)
+        end
+
+        class << self
+          # Create a Markdown language instance
+          #
+          # @param options [Hash] Commonmarker parse options
+          # @return [Language] Markdown language
+          def markdown(options: {})
+            new(:markdown, options: options)
+          end
+
+          # Load language from library path (API compatibility)
+          #
+          # @param _path [String] Ignored - Commonmarker 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
+        end
+
+        Markdown::Merge::BackendSupport.configure_markdown_only_language_class!(
+          self,
+          backend_label: 'Commonmarker'
+        )
+      end
+
+      # Commonmarker parser wrapper
+      class Parser < TreeHaver::Base::Parser
+        # 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 'Commonmarker not available'
+
+          opts = language.options || {}
+          doc = ::Commonmarker.parse(source, options: opts)
+          Tree.new(doc, source)
+        end
+      end
+
+      # Commonmarker node wrapper
+      #
+      # Wraps Commonmarker::Node to provide TreeHaver::Node-compatible interface.
+      class Node < TreeHaver::Base::Node
+        Markdown::Merge::BackendSupport.configure_node_link_and_navigation!(
+          self,
+          next_sibling_selector: :next_sibling,
+          prev_sibling_selector: :previous_sibling
+        )
+        Markdown::Merge::BackendSupport.configure_node_heading_and_code_block_helpers!(
+          self,
+          heading_matcher: ->(node) { node.type == 'heading' },
+          code_block_matcher: ->(node) { node.type == 'code_block' }
+        )
+
+        # Get the node type as a string
+        #
+        # @return [String] Node type
+        def type
+          inner_node.type.to_s
+        end
+
+        # Alias for TreeHaver compatibility
+        alias kind type
+
+        # Get the text content of this node
+        #
+        # @return [String] Node text
+        def text
+          if inner_node.respond_to?(:string_content)
+            begin
+              content = inner_node.string_content.to_s
+              return content unless content.empty?
+            rescue TypeError
+              # Container node - fall through
+            end
+          end
+          children.map(&:text).join
+        end
+
+        # Get child nodes
+        #
+        # @return [Array<Node>] Child nodes
+        def children
+          return [] unless inner_node.respond_to?(:each)
+
+          result = []
+          inner_node.each { |child| result << Node.new(child, source: source, lines: lines) }
+          result
+        end
+
+        # Get start byte offset
+        def start_byte
+          sp = start_point
+          calculate_byte_offset(sp[:row], sp[:column])
+        end
+
+        # Get end byte offset
+        def end_byte
+          ep = end_point
+          calculate_byte_offset(ep[:row], ep[:column])
+        end
+
+        # Get start point (0-based row/column)
+        # @return [Point] Start position
+        def start_point
+          if inner_node.respond_to?(:source_position)
+            begin
+              pos = inner_node.source_position
+              return Point.new(pos[:start_line] - 1, (pos[:start_column] || 1) - 1) if pos && pos[:start_line]
+            rescue StandardError
+              nil
+            end
+          end
+
+          # Fallback: check sourcepos (old API)
+          begin
+            pos = inner_node.sourcepos
+            return Point.new(pos[0] - 1, pos[1] - 1) if pos
+          rescue StandardError
+            nil
+          end
+
+          Point.new(0, 0)
+        end
+
+        # Get end point (0-based row/column)
+        # @return [Point] End position
+        def end_point
+          if inner_node.respond_to?(:source_position)
+            begin
+              pos = inner_node.source_position
+              return Point.new(pos[:end_line] - 1, (pos[:end_column] || 1) - 1) if pos && pos[:end_line]
+            rescue StandardError
+              nil
+            end
+          end
+
+          begin
+            pos = inner_node.sourcepos
+            return Point.new(pos[2] - 1, pos[3] - 1) if pos
+          rescue StandardError
+            nil
+          end
+
+          Point.new(0, 0)
+        end
+      end
+    end
+  end
+end

data/lib/commonmarker/merge/comment_tracker.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    CommentTracker = Markdown::Merge::CommentTracker
+  end
+end

data/lib/commonmarker/merge/debug_logger.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    # Debug logging utility for Commonmarker::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["COMMONMARKER_MERGE_DEBUG"] = "1"
+    #   DebugLogger.debug("Parsing markdown", { file: "README.md" })
+    #
+    # @example Time an operation
+    #   result = DebugLogger.time("parse") { Commonmarker.parse(source) }
+    #
+    # @see Ast::Merge::DebugLogger Base module
+    module DebugLogger
+      Markdown::Merge::WrapperSupport.configure_debug_logger!(
+        debug_logger_module: self,
+        env_var_name: 'COMMONMARKER_MERGE_DEBUG',
+        log_prefix: '[commonmarker-merge]'
+      )
+    end
+  end
+end

data/lib/commonmarker/merge/file_analysis.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    # File analysis for Markdown files using CommonMarker.
+    #
+    # This is a thin wrapper around Markdown::Merge::FileAnalysis that:
+    # - Forces the :commonmarker backend
+    # - Sets the default freeze token to "commonmarker-merge"
+    # - Exposes commonmarker-specific options
+    #
+    # @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 commonmarker-merge
+      # @return [String]
+      DEFAULT_FREEZE_TOKEN = 'commonmarker-merge'
+
+      Markdown::Merge::WrapperSupport.configure_file_analysis_subclass!(
+        self,
+        default_backend: :commonmarker
+      )
+    end
+  end
+end

data/lib/commonmarker/merge/freeze_node.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    FreezeNode = Markdown::Merge::FreezeNode
+  end
+end

data/lib/commonmarker/merge/partial_template_merger.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    # Thin Commonmarker-specific wrapper for Markdown::Merge::PartialTemplateMerger.
+    #
+    # Forces the :commonmarker backend while inheriting comment-handling and
+    # merge behavior from markdown-merge.
+    class PartialTemplateMerger < Markdown::Merge::PartialTemplateMerger
+      Result = Markdown::Merge::PartialTemplateMerger::Result
+
+      Markdown::Merge::WrapperSupport.configure_partial_template_merger_subclass!(
+        self,
+        default_backend: :commonmarker,
+        file_analysis_class: -> { FileAnalysis },
+        smart_merger_class: -> { SmartMerger }
+      )
+    end
+  end
+end

data/lib/commonmarker/merge/provider.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  # Source-preserving Markdown provider integration for Commonmarker.
+  module Merge
+    # Native Commonmarker backend configuration for the shared provider engine.
+    class Provider < Markdown::Merge::SourcePreservingProvider
+      # rubocop:disable Metrics/MethodLength -- constructor declares the complete backend boundary
+      def initialize
+        super(
+          provider_id: 'ruby.markdown.commonmarker',
+          role: :backend,
+          backend: Markdown::Merge::ProviderBackend.new(
+            id: :commonmarker,
+            package: PACKAGE_NAME,
+            dialects: %i[markdown commonmark],
+            parser: lambda { |source|
+              parser = Backend::Parser.new
+              parser.language = Backend::Language.markdown
+              parser.parse(source)
+            },
+            headings: Markdown::Merge::ProviderBackend.method(:native_headings)
+          )
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+
+    class << self
+      def merge_provider
+        @merge_provider ||= Provider.new
+      end
+
+      def register_provider!(replace: false)
+        return unless Ast::Merge.respond_to?(:register_provider)
+
+        Ast::Merge.register_provider(merge_provider, replace: replace)
+      end
+    end
+  end
+end

data/lib/commonmarker/merge/smart_merger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Commonmarker
+  module Merge
+    # Orchestrates the smart merge process for Markdown files using CommonMarker.
+    #
+    # This is a thin wrapper around Markdown::Merge::SmartMerger that:
+    # - Forces the :commonmarker backend
+    # - Sets commonmarker-specific defaults (freeze token, inner_merge_code_blocks)
+    # - Exposes commonmarker-specific options (options hash)
+    #
+    # @example Basic merge (destination customizations preserved)
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   result = merger.merge
+    #   if result.success?
+    #     File.write("output.md", result.content)
+    #   end
+    #
+    # @example Template updates win
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     preference: :template,
+    #     add_template_only_nodes: true
+    #   )
+    #   result = merger.merge
+    #
+    # @example Custom signature matching
+    #   sig_gen = ->(node) {
+    #     canonical_type = Ast::Merge::NodeTyping.merge_type_for(node) || node.type
+    #     if canonical_type == :heading
+    #       [:heading, node.header_level]  # Match by level only, not content
+    #     else
+    #       node  # Fall through to default
+    #     end
+    #   }
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     signature_generator: sig_gen
+    #   )
+    #
+    # @see Markdown::Merge::SmartMerger Underlying implementation
+    class SmartMerger < Markdown::Merge::SmartMerger
+      Markdown::Merge::WrapperSupport.configure_smart_merger_subclass!(
+        self,
+        default_backend: :commonmarker,
+        default_freeze_token: -> { DEFAULT_FREEZE_TOKEN },
+        default_inner_merge_code_blocks: -> { DEFAULT_INNER_MERGE_CODE_BLOCKS },
+        file_analysis_class: -> { FileAnalysis },
+        template_parse_error_class: -> { TemplateParseError },
+        destination_parse_error_class: -> { DestinationParseError }
+      )
+    end
+  end
+end

data/lib/commonmarker/merge/version.rb

@@ -2,10 +2,12 @@
 
 module Commonmarker
   module Merge
+    # Version namespace for this gem.
     module Version
-      VERSION = "7.0.0"
+      # Current gem version.
+      VERSION = '7.1.3'
     end
-
-    VERSION = Version::VERSION
+    # Current gem version exposed at the traditional constant location.
+    VERSION = Version::VERSION # Traditional Constant Location
   end
 end

data/lib/commonmarker/merge.rb

@@ -1,15 +1,25 @@
 # frozen_string_literal: true
 
-require "markdown-merge"
-require "commonmarker"
+require 'markdown-merge'
+require 'commonmarker'
+require_relative 'merge/version'
+require_relative 'merge/backend'
 
 module Commonmarker
   module Merge
-    extend self
+    module_function
 
-    PACKAGE_NAME = "commonmarker-merge"
-    BACKEND_REFERENCE = TreeHaver::BackendReference.new(id: "commonmarker", family: "native").freeze
+    PACKAGE_NAME = 'commonmarker-merge'
+    BACKEND_REFERENCE = TreeHaver::BackendReference.new(id: 'commonmarker', family: 'native').freeze
     TreeHaver::BackendRegistry.register(BACKEND_REFERENCE)
+    Markdown::Merge::WrapperSupport.install!(
+      wrapper_module: self,
+      require_prefix: 'commonmarker/merge',
+      default_freeze_token: 'commonmarker-merge',
+      default_inner_merge_code_blocks: false,
+      registry_tag: :commonmarker_merge,
+      merger_class: 'Commonmarker::Merge::SmartMerger'
+    )
 
     def markdown_feature_profile
       Markdown::Merge.markdown_feature_profile
@@ -21,7 +31,9 @@ module Commonmarker
 
     def markdown_backend_feature_profile(backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
       markdown_feature_profile.merge(backend: BACKEND_REFERENCE.id, backend_ref: BACKEND_REFERENCE.to_h)
     end
@@ -42,18 +54,20 @@ module Commonmarker
 
     def parse_markdown(source, dialect, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
-      ::Commonmarker.parse(source)
+      TreeHaver.with_backend(BACKEND_REFERENCE.id) { TreeHaver.parser_for(:markdown).parse(source) }
       normalized = Markdown::Merge.normalize_source(source)
       {
         ok: true,
         diagnostics: [],
         analysis: {
-          kind: "markdown",
+          kind: 'markdown',
           dialect: dialect,
           normalized_source: normalized,
-          root_kind: "document",
+          root_kind: 'document',
           owners: Markdown::Merge.collect_markdown_owners(normalized)
         },
         policies: []
@@ -61,7 +75,7 @@ module Commonmarker
     rescue StandardError => e
       {
         ok: false,
-        diagnostics: [{ severity: "error", category: "parse_error", message: e.message }],
+        diagnostics: [{ severity: 'error', category: 'parse_error', message: e.message }],
         policies: []
       }
     end
@@ -72,14 +86,44 @@ module Commonmarker
 
     def merge_markdown(template_source, destination_source, dialect, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
+
+      template = parse_markdown(template_source, dialect, backend: backend)
+      return template unless template[:ok]
 
-      Markdown::Merge.merge_markdown(template_source, destination_source, dialect)
+      destination = parse_markdown(destination_source, dialect, backend: backend)
+      return destination unless destination[:ok]
+
+      destination_sections = Markdown::Merge.collect_markdown_sections(
+        destination.dig(:analysis, :normalized_source),
+        destination.dig(:analysis, :owners)
+      )
+      template_sections = Markdown::Merge.collect_markdown_sections(
+        template.dig(:analysis, :normalized_source),
+        template.dig(:analysis, :owners)
+      )
+      destination_paths = destination_sections.to_h { |section| [section[:path], true] }
+      merged_sections = destination_sections.map { |section| section[:text] }.reject(&:empty?) +
+                        template_sections
+                        .reject { |section| destination_paths[section[:path]] || section[:text].empty? }
+                        .map { |section| section[:text] }
+
+      {
+        ok: true,
+        diagnostics: [],
+        output: "#{merged_sections.join("\n\n").strip}\n",
+        policies: []
+      }
     end
 
-    def merge_markdown_with_reviewed_nested_outputs(template_source, destination_source, dialect, review_state, applied_children, backend: nil)
+    def merge_markdown_with_reviewed_nested_outputs(template_source, destination_source, dialect, review_state,
+                                                    applied_children, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
       Markdown::Merge.merge_markdown_with_reviewed_nested_outputs(
         template_source,
@@ -90,9 +134,12 @@ module Commonmarker
       )
     end
 
-    def merge_markdown_with_reviewed_nested_outputs_from_replay_bundle(template_source, destination_source, dialect, replay_bundle, backend: nil)
+    def merge_markdown_with_reviewed_nested_outputs_from_replay_bundle(template_source, destination_source, dialect,
+                                                                       replay_bundle, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
       Markdown::Merge.merge_markdown_with_reviewed_nested_outputs_from_replay_bundle(
         template_source,
@@ -102,9 +149,12 @@ module Commonmarker
       )
     end
 
-    def merge_markdown_with_reviewed_nested_outputs_from_replay_bundle_envelope(template_source, destination_source, dialect, envelope, backend: nil)
+    def merge_markdown_with_reviewed_nested_outputs_from_replay_bundle_envelope(template_source, destination_source,
+                                                                                dialect, envelope, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
       Markdown::Merge.merge_markdown_with_reviewed_nested_outputs_from_replay_bundle_envelope(
         template_source,
@@ -114,9 +164,12 @@ module Commonmarker
       )
     end
 
-    def merge_markdown_with_reviewed_nested_outputs_from_review_state(template_source, destination_source, dialect, review_state, backend: nil)
+    def merge_markdown_with_reviewed_nested_outputs_from_review_state(template_source, destination_source, dialect,
+                                                                      review_state, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
       Markdown::Merge.merge_markdown_with_reviewed_nested_outputs_from_review_state(
         template_source,
@@ -126,9 +179,12 @@ module Commonmarker
       )
     end
 
-    def merge_markdown_with_reviewed_nested_outputs_from_review_state_envelope(template_source, destination_source, dialect, envelope, backend: nil)
+    def merge_markdown_with_reviewed_nested_outputs_from_review_state_envelope(template_source, destination_source,
+                                                                               dialect, envelope, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
-      return unsupported_feature_result("Unsupported Markdown backend #{requested}.") unless requested == BACKEND_REFERENCE.id
+      unless requested == BACKEND_REFERENCE.id
+        return unsupported_feature_result("Unsupported Markdown backend #{requested}.")
+      end
 
       Markdown::Merge.merge_markdown_with_reviewed_nested_outputs_from_review_state_envelope(
         template_source,
@@ -145,7 +201,7 @@ module Commonmarker
     def unsupported_feature_result(message)
       {
         ok: false,
-        diagnostics: [{ severity: "error", category: "unsupported_feature", message: message }],
+        diagnostics: [{ severity: 'error', category: 'unsupported_feature', message: message }],
         policies: []
       }
     end
@@ -168,3 +224,8 @@ module Commonmarker
     )
   end
 end
+
+require_relative 'merge/provider'
+Commonmarker::Merge.register_provider!
+
+Commonmarker::Merge.ensure_backend_loaded!

data/lib/commonmarker-merge.rb

@@ -1,3 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "commonmarker/merge"
+require_relative 'commonmarker/merge'
+require 'version_gem'
+require_relative 'commonmarker/merge/version'
+
+Commonmarker::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/sig/commonmarker/merge.rbs

@@ -0,0 +1,15 @@
+module Commonmarker
+  module Merge
+    module Version
+      VERSION: String
+    end
+    VERSION: String
+
+    class Provider < Markdown::Merge::SourcePreservingProvider
+      def initialize: () -> void
+    end
+
+    def self.merge_provider: () -> Provider
+    def self.register_provider!: (?replace: bool) -> untyped
+  end
+end