markdown-merge 1.0.3 → 7.1.1

data/lib/markdown/merge/partial_template_merger.rb

@@ -30,9 +30,25 @@ module Markdown
     #   )
     #
     class PartialTemplateMerger < Ast::Merge::PartialTemplateMergerBase
+      include PreservationSupport
+
       # Re-export Result class from base for convenience
       Result = Ast::Merge::PartialTemplateMergerBase::Result
 
+      class << self
+        def default_backend
+          :markly
+        end
+
+        def file_analysis_class
+          FileAnalysis
+        end
+
+        def smart_merger_class
+          SmartMerger
+        end
+      end
+
       # @return [Symbol] Backend to use (:markly, :commonmarker)
       attr_reader :backend
 
@@ -57,7 +73,7 @@ module Markdown
         destination:,
         anchor:,
         boundary: nil,
-        backend: :markly,
+        backend: self.class.default_backend,
         preference: :template,
         add_missing: true,
         when_missing: :skip,
@@ -117,7 +133,7 @@ module Markdown
             changed: result.changed,
             stats: result.stats.merge(problems: problems.all),
             injection_point: result.injection_point,
-            message: result.message,
+            message: result.message
           )
         else
           result
@@ -126,15 +142,37 @@ module Markdown
 
       protected
 
+      def merge_section_content(section_content, section_context: nil)
+        return super unless replace_mode?
+
+        template_analysis = create_analysis(template)
+        preserved_fragment_insertions = preserved_destination_insertions(
+          create_analysis(section_content),
+          template_analysis,
+          source_remove_plan: section_context&.fetch(:source_remove_plan, nil),
+          destination_section_statements: section_context&.fetch(:section_statements, nil),
+          destination_section_analysis: section_context&.fetch(:analysis, nil)
+        )
+
+        return [template, { mode: :replace }] if preserved_fragment_insertions.empty?
+
+        preservation_stats = replace_mode_preservation_stats(preserved_fragment_insertions)
+
+        [
+          render_template_with_preserved_insertions(template_analysis, preserved_fragment_insertions),
+          preservation_stats
+        ]
+      end
+
       # Validate the backend parameter.
       #
       # @param backend [Symbol] The backend to validate
       # @raise [ArgumentError] If backend is not supported
       def validate_backend!(backend)
-        valid_backends = [:markly, :commonmarker]
+        valid_backends = %i[auto markly commonmarker kramdown]
         return if valid_backends.include?(backend.to_sym)
 
-        raise ArgumentError, "Unknown backend: #{backend}. Supported: #{valid_backends.join(", ")}"
+        raise ArgumentError, "Unknown backend: #{backend}. Supported: #{valid_backends.join(', ')}"
       end
 
       # Create a FileAnalysis for the given content.
@@ -142,7 +180,7 @@ module Markdown
       # @param content [String] The content to analyze
       # @return [FileAnalysis] A FileAnalysis instance
       def create_analysis(content)
-        FileAnalysis.new(content, backend: backend)
+        self.class.file_analysis_class.new(content, backend: backend)
       end
 
       # Create a SmartMerger for merging the section.
@@ -155,7 +193,7 @@ module Markdown
         options = {
           preference: preference,
           add_template_only_nodes: add_missing,
-          backend: backend,
+          backend: backend
         }
 
         # Use custom signature generator if provided, otherwise use position-based
@@ -166,7 +204,7 @@ module Markdown
         options[:node_typing] = node_typing if node_typing
         options[:match_refiner] = match_refiner if match_refiner
 
-        SmartMerger.new(template_content, destination_content, **options)
+        self.class.smart_merger_class.new(template_content, destination_content, **options)
       end
 
       # Build a signature generator that uses type-based matching for tables.
@@ -199,10 +237,10 @@ module Markdown
         # provide a custom signature_generator.
         lambda do |node|
           type_str = node.type.to_s
-          if type_str == "table"
+          if type_str == 'table'
             # All tables within a section merge get the same signature.
             # This ensures template table replaces destination table.
-            [:table, :section_table]
+            %i[table section_table]
           else
             # Return node for default signature computation
             node
@@ -236,12 +274,12 @@ module Markdown
 
           ((anchor.index + 1)...statements.length).each do |idx|
             stmt = statements[idx]
-            if heading_type?(stmt.type)
-              stmt_level = get_heading_level(stmt)
-              if stmt_level && anchor_level && stmt_level <= anchor_level
-                # Found next heading of same or higher level - section ends before it
-                return idx - 1
-              end
+            next unless heading_type?(stmt.type)
+
+            stmt_level = get_heading_level(stmt)
+            if stmt_level && anchor_level && stmt_level <= anchor_level
+              # Found next heading of same or higher level - section ends before it
+              return idx - 1
             end
           end
 
@@ -250,16 +288,12 @@ module Markdown
         end
 
         # For non-headings, use boundary if specified and found
-        if injection_point.boundary
-          return injection_point.boundary.index - 1
-        end
+        return injection_point.boundary.index - 1 if injection_point.boundary
 
         # Otherwise, find next node of same type
         ((anchor.index + 1)...statements.length).each do |idx|
           stmt = statements[idx]
-          if stmt.type == anchor_type
-            return idx - 1
-          end
+          return idx - 1 if stmt.type == anchor_type
         end
 
         # Section extends to end of document
@@ -274,12 +308,10 @@ module Markdown
       # @param node [Object] The node to convert
       # @param analysis [FileAnalysis, nil] The analysis object for source lookup
       # @return [String] The source text
-      def node_to_text(node, analysis = nil)
+      def node_to_source(node, analysis = nil)
         # Unwrap if needed
         inner = node
-        while inner.respond_to?(:inner_node) && inner.inner_node != inner
-          inner = inner.inner_node
-        end
+        inner = inner.inner_node while inner.respond_to?(:inner_node) && inner.inner_node != inner
 
         # Prefer source-based extraction to preserve original formatting
         # (link references, table padding, etc.)
@@ -302,18 +334,207 @@ module Markdown
         elsif inner.respond_to?(:to_s)
           inner.to_s
         else
-          ""
+          ''
         end
       end
 
+      alias node_to_text node_to_source
+
       private
 
+      def replace_mode_preservation_stats(insertions)
+        comment_count = 0
+        link_definition_count = 0
+
+        insertions.each_value do |fragments|
+          fragments.each do |fragment|
+            case fragment[:kind]
+            when :standalone_comment
+              comment_count += 1
+            when :link_definition
+              link_definition_count += 1
+            end
+          end
+        end
+
+        {
+          mode: :replace,
+          preserved_destination_comment_fragments: comment_count,
+          preserved_destination_link_definitions: link_definition_count
+        }.reject { |_key, value| value == 0 }
+      end
+
+      def preserved_destination_insertions(destination_analysis, template_analysis, source_remove_plan: nil,
+                                           destination_section_statements: nil, destination_section_analysis: nil)
+        insertions = Hash.new { |hash, key| hash[key] = [] }
+        remove_plan_owned_comment_region_keys = if source_remove_plan
+                                                  rebase_preserved_comment_keys(
+                                                    remove_plan_preserved_comment_keys(source_remove_plan),
+                                                    line_offset: source_remove_plan.remove_start_line - 1
+                                                  )
+                                                else
+                                                  Set.new
+                                                end
+        template_has_standalone_comments = template_analysis.statements.any? do |statement|
+          standalone_comment_node?(statement, template_analysis)
+        end
+        template_link_definition_signatures = template_analysis.statements.each_with_object(Set.new) do |statement, signatures|
+          signatures << statement.signature if link_definition_node?(statement)
+        end
+
+        preserve_comment_insertions_from_remove_plan(
+          insertions,
+          source_remove_plan,
+          destination_section_statements,
+          destination_section_analysis || destination_analysis,
+          template_has_standalone_comments: template_has_standalone_comments
+        )
+
+        structural_index = 0
+        pending_gap_count = 0
+
+        destination_analysis.statements.each do |statement|
+          if structural_preservation_statement?(statement, destination_analysis)
+            structural_index += 1
+            pending_gap_count = 0
+          elsif gap_line_node?(statement)
+            pending_gap_count += 1 if insertions[structural_index].any?
+          else
+            next if remove_plan_owns_comment_node?(
+              statement,
+              destination_analysis,
+              source_remove_plan,
+              preserved_comment_keys: remove_plan_owned_comment_region_keys
+            )
+
+            fragment = preserved_fragment_for_node(
+              statement,
+              destination_analysis,
+              template_has_standalone_comments: template_has_standalone_comments,
+              template_link_definition_signatures: template_link_definition_signatures
+            )
+            next unless fragment
+
+            append_preserved_fragment(insertions, structural_index, fragment, gap_count: pending_gap_count)
+            pending_gap_count = 0
+          end
+        end
+
+        insertions.reject { |_index, fragments| fragments.empty? }
+      end
+
+      def preserve_comment_insertions_from_remove_plan(insertions, source_remove_plan, destination_section_statements,
+                                                       destination_section_analysis, template_has_standalone_comments:)
+        return if template_has_standalone_comments
+        return unless source_remove_plan && destination_section_statements && destination_section_analysis
+
+        structural_index_by_owner, final_structural_index = structural_index_lookup(destination_section_statements,
+                                                                                    destination_section_analysis)
+        remove_plan_comment_insertion_specs(
+          source_remove_plan,
+          insertion_index_by_owner: structural_index_by_owner,
+          final_insertion_index: final_structural_index
+        ).each do |spec|
+          append_preserved_fragment(
+            insertions,
+            spec.fetch(:insertion_index),
+            spec.fetch(:fragment),
+            gap_count: spec.fetch(:gap_count)
+          )
+        end
+      end
+
+      def structural_index_lookup(statements, analysis)
+        structural_index = 0
+        lookup = {}
+
+        Array(statements).each do |statement|
+          owner = statement.respond_to?(:node) ? statement.node : statement
+          lookup[attachment_owner_key(owner)] = structural_index
+
+          next unless structural_preservation_statement?(statement, analysis)
+
+          structural_index += 1
+        end
+
+        [lookup, structural_index]
+      end
+
+      def append_preserved_fragment(insertions, structural_index, fragment, gap_count: 0)
+        if insertions[structural_index].any?
+          fragment[:separator] = preserved_fragment_separator(
+            gap_count: gap_count,
+            previous_kind: insertions[structural_index].last.fetch(:kind),
+            current_kind: fragment.fetch(:kind)
+          )
+        end
+
+        insertions[structural_index] << fragment
+      end
+
+      def render_template_with_preserved_insertions(template_analysis, insertions)
+        result = +''
+        structural_index = 0
+        statements = template_analysis.statements
+        index = 0
+
+        while index < statements.length
+          statement = statements[index]
+
+          if gap_line_node?(statement) && insertions.key?(structural_index) && next_structural_statement_after?(
+            statements, index, template_analysis
+          )
+            index += 1 while index < statements.length && gap_line_node?(statements[index])
+            result = append_preserved_fragments(result, insertions.delete(structural_index))
+            next
+          end
+
+          result << node_to_source(statement, template_analysis)
+          structural_index += 1 if structural_preservation_statement?(statement, template_analysis)
+          index += 1
+        end
+
+        if insertions.key?(structural_index)
+          result = append_preserved_fragments(result, insertions.delete(structural_index))
+        end
+
+        result
+      end
+
+      def append_preserved_fragments(content, fragments)
+        result = content.sub(/\n+\z/, "\n")
+
+        unless result.empty?
+          if result.end_with?("\n")
+            result << "\n" unless result.end_with?("\n\n")
+          else
+            result << "\n\n"
+          end
+        end
+
+        result << render_preserved_fragment_block(fragments)
+        result << "\n"
+        result << "\n" unless result.end_with?("\n\n")
+        result
+      end
+
+      def render_preserved_fragment_block(fragments)
+        fragments.each_with_object(+'').with_index do |(fragment, result), index|
+          result << fragment[:separator] if index.positive?
+          result << fragment.fetch(:text)
+        end
+      end
+
+      def next_structural_statement_after?(statements, start_index, analysis)
+        statements[(start_index + 1)..]&.any? { |statement| structural_preservation_statement?(statement, analysis) }
+      end
+
       # Check if a type represents a heading node.
       #
       # @param type [Symbol, String] The node type
       # @return [Boolean] true if this is a heading type
       def heading_type?(type)
-        type.to_s == "heading" || type == :heading || type == :header
+        type.to_s == 'heading' || type == :heading || type == :header
       end
 
       # Get the heading level from a statement.

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