markdown-merge 7.0.0 → 7.1.1

data/lib/markdown/merge/preservation_support.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Shared Markdown-local helper methods for statement classification,
+    # standalone comment fragment preservation, and remove-plan-backed range filtering.
+    #
+    # Provides the canonical gap-line / blank-gap-line / non-blank-gap-line /
+    # structural-for-preservation predicate set used by both SmartMergerBase
+    # (removal mode) and PartialTemplateMerger (replace-mode insertion indexing).
+    # Both classes should call these predicates rather than performing direct
+    # is_a?(GapLineNode) checks.
+    module PreservationSupport
+      private
+
+      def normalized_preserved_fragment_text(text)
+        text.to_s.sub(/\n+\z/, '')
+      end
+
+      def standalone_comment_text?(text)
+        normalized_preserved_fragment_text(text).strip.match?(CommentTracker::STANDALONE_HTML_COMMENT_REGEX)
+      end
+
+      def standalone_comment_node?(node, analysis)
+        return false unless node.respond_to?(:source_position)
+        return false unless analysis.respond_to?(:comment_tracker)
+        return false unless analysis.respond_to?(:comment_node_at)
+        return false unless analysis.comment_tracker
+
+        pos = node.source_position
+        start_line = pos&.dig(:start_line)
+        end_line = pos&.dig(:end_line)
+        return false unless start_line && end_line
+        return false unless start_line == end_line
+
+        !!analysis.comment_node_at(start_line)
+      end
+
+      def link_definition_node?(node)
+        node.is_a?(LinkDefinitionNode) || (node.respond_to?(:merge_type) && node.merge_type == :link_definition)
+      end
+
+      def gap_line_node?(node)
+        node.is_a?(GapLineNode) ||
+          (node.respond_to?(:merge_type) && node.merge_type == :gap_line) ||
+          (node.respond_to?(:type) && node.type == :gap_line)
+      end
+
+      def blank_gap_line_node?(node)
+        return false unless gap_line_node?(node)
+        return node.blank? if node.respond_to?(:blank?)
+
+        text = if node.respond_to?(:text)
+                 node.text
+               elsif node.respond_to?(:content)
+                 node.content
+               else
+                 ''
+               end
+
+        text.to_s.strip.empty?
+      end
+
+      # Returns true when the node is a gap line whose content is non-blank
+      # (e.g. a consumed link-reference definition or similar inline content
+      # that was mapped to a GapLineNode).
+      #
+      # This is the canonical replacement for `node.is_a?(GapLineNode) && !node.blank?`
+      # and handles wrapped gap-line statement nodes uniformly alongside real
+      # GapLineNode instances.
+      #
+      # @param node [Object] The node to classify
+      # @return [Boolean] true when the node is a gap line with non-blank content
+      def non_blank_gap_line_node?(node)
+        gap_line_node?(node) && !blank_gap_line_node?(node)
+      end
+
+      def structural_preservation_statement?(statement, analysis)
+        !gap_line_node?(statement) &&
+          !standalone_comment_node?(statement, analysis) &&
+          !link_definition_node?(statement)
+      end
+
+      def standalone_comment_region?(region)
+        standalone_comment_text?(region.respond_to?(:text) ? region.text : nil)
+      end
+
+      def preserved_comment_region_key(region)
+        [
+          region.respond_to?(:start_line) ? region.start_line : nil,
+          region.respond_to?(:end_line) ? region.end_line : nil,
+          normalized_preserved_fragment_text(region.respond_to?(:text) ? region.text : nil)
+        ]
+      end
+
+      def preserved_comment_node_key(node, analysis, text: nil)
+        pos = node.respond_to?(:source_position) ? node.source_position : nil
+
+        [
+          pos&.dig(:start_line),
+          pos&.dig(:end_line),
+          normalized_preserved_fragment_text(text || source_text_for_preserved_node(node, analysis))
+        ]
+      end
+
+      def region_within_removed_range?(region, remove_plan)
+        return false unless region
+
+        start_line = region.respond_to?(:start_line) ? region.start_line : nil
+        end_line = region.respond_to?(:end_line) ? region.end_line : nil
+        return true unless start_line && end_line
+
+        start_line >= remove_plan.remove_start_line && end_line <= remove_plan.remove_end_line
+      end
+
+      def remove_plan_preserved_comment_regions(remove_plan)
+        return [] unless remove_plan
+
+        regions = Array(remove_plan.promoted_comment_regions)
+        regions << remove_plan.trailing_boundary&.comment_attachment&.leading_region
+
+        seen = Set.new
+        regions.each_with_object([]) do |region, preserved_regions|
+          next unless standalone_comment_region?(region)
+          next unless region_within_removed_range?(region, remove_plan)
+
+          region_key = preserved_comment_region_key(region)
+          next if seen.include?(region_key)
+
+          seen << region_key
+          preserved_regions << region
+        end
+      end
+
+      def remove_plan_preserved_comment_keys(remove_plan)
+        remove_plan_preserved_comment_regions(remove_plan).each_with_object(Set.new) do |region, keys|
+          keys << preserved_comment_region_key(region)
+        end
+      end
+
+      def rebase_preserved_comment_keys(keys, line_offset:)
+        Array(keys).each_with_object(Set.new) do |key, rebased_keys|
+          start_line, end_line, text = Array(key)
+          rebased_keys << [
+            start_line ? start_line - line_offset : nil,
+            end_line ? end_line - line_offset : nil,
+            text
+          ]
+        end
+      end
+
+      def remove_plan_owns_comment_node?(node, analysis, remove_plan, preserved_comment_keys: nil)
+        return false unless remove_plan
+        return false unless standalone_comment_node?(node, analysis)
+
+        keys = preserved_comment_keys || remove_plan_preserved_comment_keys(remove_plan)
+        region = comment_region_for_node(node, analysis, kind: :orphan)
+        return false unless region_within_removed_range?(region, remove_plan)
+
+        keys.include?(preserved_comment_region_key(region))
+      end
+
+      def remove_plan_preserved_comment_keys_for_nodes(remove_plan, nodes:, analysis:)
+        keys = remove_plan_preserved_comment_keys(remove_plan)
+
+        Array(nodes).each do |node|
+          next unless standalone_comment_node?(node, analysis)
+
+          region = comment_region_for_node(node, analysis, kind: :orphan)
+          next unless region_within_removed_range?(region, remove_plan)
+
+          keys << preserved_comment_node_key(node, analysis)
+        end
+
+        keys
+      end
+
+      def remove_plan_comment_insertion_specs(remove_plan, insertion_index_by_owner:, final_insertion_index:)
+        return [] unless remove_plan
+
+        allowed_region_keys = remove_plan_preserved_comment_keys(remove_plan)
+        seen_region_keys = Set.new
+
+        Array(remove_plan.removed_attachments).each_with_object([]) do |attachment, specs|
+          append_remove_plan_comment_insertion_spec(
+            specs,
+            region: attachment.respond_to?(:leading_region) ? attachment.leading_region : nil,
+            insertion_index: insertion_index_by_owner[attachment_owner_key(attachment)],
+            gap_count: blank_gap_count(attachment.respond_to?(:leading_gap) ? attachment.leading_gap : nil),
+            allowed_region_keys: allowed_region_keys,
+            seen_region_keys: seen_region_keys
+          )
+        end.tap do |specs|
+          append_remove_plan_comment_insertion_spec(
+            specs,
+            region: remove_plan.trailing_boundary&.comment_attachment&.leading_region,
+            insertion_index: final_insertion_index,
+            gap_count: blank_gap_count(remove_plan.trailing_boundary&.comment_attachment&.leading_gap),
+            allowed_region_keys: allowed_region_keys,
+            seen_region_keys: seen_region_keys
+          )
+        end
+      end
+
+      def comment_region_for_node(node, analysis, kind: :orphan, full_line_only: true)
+        return unless node.respond_to?(:source_position)
+        return unless analysis.respond_to?(:comment_region_for_range)
+
+        pos = node.source_position
+        start_line = pos&.dig(:start_line)
+        end_line = pos&.dig(:end_line)
+        return unless start_line && end_line
+
+        analysis.comment_region_for_range(start_line..end_line, kind: kind, full_line_only: full_line_only)
+      end
+
+      def preserved_fragment_for_node(
+        node,
+        analysis,
+        template_has_standalone_comments:,
+        template_link_definition_signatures:
+      )
+        if standalone_comment_node?(node, analysis)
+          return if template_has_standalone_comments
+
+          {
+            kind: :standalone_comment,
+            text: normalized_preserved_fragment_text(source_text_for_preserved_node(node, analysis))
+          }
+        elsif link_definition_node?(node)
+          return if template_link_definition_signatures.include?(node.signature)
+
+          {
+            kind: :link_definition,
+            text: normalized_preserved_fragment_text(source_text_for_preserved_node(node, analysis))
+          }
+        end
+      end
+
+      def preserved_fragment_separator(gap_count:, previous_kind:, current_kind:)
+        return "\n\n" if gap_count.positive?
+        return "\n" if previous_kind == :link_definition && current_kind == :link_definition
+
+        "\n\n"
+      end
+
+      def blank_gap_count(gap)
+        return 0 unless gap&.respond_to?(:blank_line_count)
+
+        gap.blank_line_count
+      end
+
+      def attachment_owner_key(owner_or_attachment)
+        owner = if owner_or_attachment.respond_to?(:owner)
+                  owner_or_attachment.owner
+                else
+                  owner_or_attachment
+                end
+
+        owner&.object_id
+      end
+
+      def source_text_for_preserved_node(node, analysis)
+        if respond_to?(:node_to_source, true)
+          node_to_source(node, analysis)
+        else
+          ''
+        end
+      end
+
+      def append_remove_plan_comment_insertion_spec(specs, region:, insertion_index:, gap_count:, allowed_region_keys:,
+                                                    seen_region_keys:)
+        return unless region && insertion_index
+
+        region_key = preserved_comment_region_key(region)
+        return unless allowed_region_keys.include?(region_key)
+        return if seen_region_keys.include?(region_key)
+
+        seen_region_keys << region_key
+        specs << {
+          insertion_index: insertion_index,
+          fragment: {
+            kind: :standalone_comment,
+            text: normalized_preserved_fragment_text(region.text)
+          },
+          gap_count: gap_count
+        }
+      end
+    end
+  end
+end

data/lib/markdown/merge/smart_merger.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Orchestrates the smart merge process for Markdown files using tree_haver backends.
+    #
+    # Extends SmartMergerBase with backend-agnostic parsing via tree_haver.
+    # Supports both Commonmarker and Markly backends.
+    #
+    # Uses FileAnalysis, FileAligner, ConflictResolver, and MergeResult to
+    # merge two Markdown files intelligently. Freeze blocks marked with
+    # HTML comments are preserved exactly as-is.
+    #
+    # SmartMerger provides flexible configuration for different merge scenarios:
+    # - Preserve destination customizations (default)
+    # - Apply template updates
+    # - Add new sections from template
+    # - Inner-merge fenced code blocks using language-specific mergers (optional)
+    #
+    # @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 With specific backend
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     backend: :markly
+    #   )
+    #   result = merger.merge
+    #
+    # @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 FileAnalysis
+    # @see SmartMergerBase
+    class SmartMerger < SmartMergerBase
+      VALID_BACKENDS = %i[auto commonmarker markly kramdown].freeze
+
+      class << self
+        def default_backend
+          :auto
+        end
+
+        def default_freeze_token
+          FileAnalysis::DEFAULT_FREEZE_TOKEN
+        end
+
+        def default_inner_merge_code_blocks
+          false
+        end
+
+        def default_parser_options
+          {}
+        end
+
+        def file_analysis_class
+          FileAnalysis
+        end
+
+        def template_parse_error_class
+          TemplateParseError
+        end
+
+        def destination_parse_error_class
+          DestinationParseError
+        end
+      end
+
+      # @return [Symbol] The backend being used (:commonmarker, :markly)
+      attr_reader :backend
+
+      # Creates a new SmartMerger for intelligent Markdown file merging.
+      #
+      # @param template_content [String] Template Markdown source code
+      # @param dest_content [String] Destination Markdown source code
+      #
+      # @param backend [Symbol] Backend to use for parsing:
+      #   - `:commonmarker` - Use Commonmarker (comrak Rust parser)
+      #   - `:markly` - Use Markly (cmark-gfm C library)
+      #   - `:auto` (default) - Auto-detect available backend
+      #
+      # @param signature_generator [Proc, nil] Optional proc to generate custom node signatures.
+      #   The proc receives a node (wrapped with canonical merge_type) and should return one of:
+      #   - An array representing the node's signature
+      #   - `nil` to indicate the node should have no signature
+      #   - The original node to fall through to default signature computation
+      #
+      # @param preference [Symbol] Controls which version to use when nodes
+      #   have matching signatures but different content:
+      #   - `:destination` (default) - Use destination version (preserves customizations)
+      #   - `:template` - Use template version (applies updates)
+      #
+      # @param add_template_only_nodes [Boolean] Controls whether to add nodes that only
+      #   exist in template:
+      #   - `false` (default) - Skip template-only nodes
+      #   - `true` - Add template-only nodes to result
+      #
+      # @param inner_merge_code_blocks [Boolean, CodeBlockMerger] Controls inner-merge for
+      #   fenced code blocks:
+      #   - `true` - Enable inner-merge using default CodeBlockMerger
+      #   - `false` (default) - Disable inner-merge (use standard conflict resolution)
+      #   - `CodeBlockMerger` instance - Use custom CodeBlockMerger
+      #
+      # @param remove_template_missing_nodes [Boolean] Controls whether destination-only
+      #   structural nodes should be removed instead of preserved. Standalone HTML
+      #   comment-only fragments, freeze blocks, and link reference definitions remain
+      #   preserved when enabled.
+      #
+      # @param freeze_token [String] Token to use for freeze block markers.
+      #   Default: "markdown-merge"
+      #   Looks for: <!-- markdown-merge:freeze --> / <!-- markdown-merge:unfreeze -->
+      #
+      # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching of
+      #   unmatched nodes. Default: nil (fuzzy matching disabled).
+      #   Set to TableMatchRefiner.new to enable fuzzy table matching.
+      #
+      # @param node_typing [Hash{Symbol,String => #call}, nil] Node typing configuration
+      #   for per-node-type merge preferences. Maps node type names to callables.
+      #
+      # @param parser_options [Hash] Backend-specific parser options.
+      #   For commonmarker: { options: {} }
+      #   For markly: { flags: Markly::DEFAULT, extensions: [:table] }
+      #
+      # @raise [TemplateParseError] If template has syntax errors
+      # @raise [DestinationParseError] If destination has syntax errors
+      def initialize(
+        template_content,
+        dest_content,
+        backend: self.class.default_backend,
+        signature_generator: nil,
+        preference: :destination,
+        add_template_only_nodes: false,
+        inner_merge_code_blocks: self.class.default_inner_merge_code_blocks,
+        inner_merge_lists: false,
+        remove_template_missing_nodes: false,
+        freeze_token: self.class.default_freeze_token,
+        match_refiner: nil,
+        node_typing: nil,
+        **parser_options
+      )
+        validate_backend!(backend)
+
+        @requested_backend = backend
+        @parser_options = self.class.default_parser_options.merge(parser_options)
+
+        super(
+          template_content,
+          dest_content,
+          signature_generator: signature_generator,
+          preference: preference,
+          add_template_only_nodes: add_template_only_nodes,
+          inner_merge_code_blocks: inner_merge_code_blocks,
+          inner_merge_lists: inner_merge_lists,
+          remove_template_missing_nodes: remove_template_missing_nodes,
+          freeze_token: freeze_token,
+          match_refiner: match_refiner,
+          node_typing: node_typing,
+          # Pass through for FileAnalysis
+          backend: backend,
+          **parser_options,
+        )
+
+        # Capture the resolved backend from template analysis
+        @backend = @template_analysis.backend
+      end
+
+      # Create a FileAnalysis instance for parsing.
+      #
+      # @param content [String] Markdown content to analyze
+      # @param options [Hash] Analysis options
+      # @return [FileAnalysis] File analysis instance
+      def create_file_analysis(content, **opts)
+        self.class.file_analysis_class.new(
+          content,
+          backend: opts[:backend] || @requested_backend,
+          freeze_token: opts[:freeze_token],
+          signature_generator: opts[:signature_generator],
+          **@parser_options
+        )
+      end
+
+      # Returns the TemplateParseError class to use.
+      #
+      # @return [Class] Markdown::Merge::TemplateParseError
+      def template_parse_error_class
+        self.class.template_parse_error_class
+      end
+
+      # Returns the DestinationParseError class to use.
+      #
+      # @return [Class] Markdown::Merge::DestinationParseError
+      def destination_parse_error_class
+        self.class.destination_parse_error_class
+      end
+
+      # Convert a node to its source text.
+      #
+      # Handles wrapped nodes from NodeTypeNormalizer, gap line nodes,
+      # and link definition nodes created during gap detection.
+      #
+      # @param node [Object] Node to convert (may be wrapped)
+      # @param analysis [FileAnalysis] Analysis for source lookup
+      # @return [String] Source text
+      def node_to_source(node, analysis)
+        # Check for any FreezeNode type (base class or subclass)
+        return node.full_text if node.is_a?(Ast::Merge::FreezeNodeBase)
+
+        # Handle gap line nodes (created for blank lines and link definitions)
+        return node.content if node.is_a?(LinkDefinitionNode) || node.is_a?(GapLineNode)
+
+        # Unwrap if needed to access source_position
+        raw_node = Ast::Merge::NodeTyping.unwrap(node)
+
+        pos = raw_node.source_position
+        start_line = pos&.dig(:start_line)
+        end_line = pos&.dig(:end_line)
+
+        # Fall back to to_commonmark if no position info
+        return raw_node.to_commonmark unless start_line && end_line
+
+        # Get source from line range
+        source = analysis.source_range(start_line, end_line)
+
+        # Handle Markly's buggy position reporting for :html nodes
+        # where end_line < start_line results in empty source_range.
+        # Fall back to to_commonmark in that case.
+        if source.empty? && raw_node.respond_to?(:to_commonmark)
+          raw_node.to_commonmark.chomp
+        else
+          source
+        end
+      end
+
+      private
+
+      def validate_backend!(backend)
+        normalized_backend = backend.respond_to?(:to_sym) ? backend.to_sym : backend
+        return if VALID_BACKENDS.include?(normalized_backend)
+
+        raise ArgumentError, "Unknown backend: #{backend}"
+      end
+    end
+  end
+end