markdown-merge 7.0.0 → 7.1.3

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/rspec/shared_examples/source_preserving_provider.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'ast/merge/rspec/shared_examples'
+
+# rubocop:disable Metrics/BlockLength -- the conservative provider safety contract is intentionally executable as one matrix
+RSpec.shared_examples 'Markdown::Merge::SourcePreservingProvider' do
+  let(:base) { "# Alpha\n\nalpha\n\n# Beta\n\nbeta\n" }
+  let(:stable) { "# Stable\n\nstable\n" }
+  let(:provider_conformance) do
+    {
+      dialect: provider_dialect,
+      backend: provider_backend,
+      profile_id: :source_preserving,
+      role: provider_role,
+      requests: {
+        analyze: { source: stable },
+        diff2: { before_source: stable, after_source: stable.sub('stable', 'changed') },
+        merge2: { current_source: stable, incoming_source: "#{stable}# Added\n\nadded\n" },
+        merge3: {
+          base_source: base,
+          ours_source: base.sub('alpha', 'ours'),
+          theirs_source: base.sub('beta', 'theirs')
+        }
+      },
+      invalid_merge3: {
+        base_source: stable,
+        ours_source: "# Broken\0\n",
+        theirs_source: stable,
+        source_role: :ours
+      },
+      base_adversarial_merge3: {
+        request: {
+          base_source: "# Obsolete\n\nold\n\n#{stable}",
+          ours_source: "# Obsolete\n\nold\n\n#{stable}",
+          theirs_source: stable
+        },
+        expected_value: [[1, 'Stable']]
+      },
+      parse_output: lambda { |source|
+        provider.analyze(source: source).dig(:analysis, :owners).map { |owner| owner.fetch(:signature) }
+      }
+    }
+  end
+
+  it 'passes the shared provider contract for every operation and exact selector' do
+    Ast::Merge.register_provider(provider, replace: true)
+    registration = Ast::Merge::ProviderContract.validate_provider!(provider)
+    selectors = {
+      provider_id: provider.provider_id,
+      family: provider.family,
+      dialect: provider_dialect,
+      backend: provider_backend,
+      profile_id: :source_preserving
+    }
+
+    expect(registration.dig(:capabilities, :role)).to eq(provider_role)
+    expect(Ast::Merge.resolve_provider(**selectors, operation: :merge3)).to equal(provider)
+    provider_conformance.fetch(:requests).each do |operation, request|
+      result = Ast::Merge.dispatch_provider(operation, selectors.merge(request))
+      expect(Ast::Merge::ProviderContract.validate_result!(operation, result)).to include(ok: true)
+    end
+    unsupported = Ast::Merge.dispatch_provider(
+      :merge3,
+      selectors.merge(provider_conformance.dig(:requests, :merge3), dialect: :unadvertised)
+    )
+    expect(unsupported).to include(
+      ok: false,
+      diagnostics: contain_exactly(hash_including(category: :unsupported_capability))
+    )
+  end
+
+  it 'advertises and resolves its exact selector' do
+    expect(provider.capabilities).to include(
+      operations: %i[analyze diff2 merge2 merge3],
+      dialects: include(provider_dialect),
+      backends: [provider_backend],
+      profiles: %i[source_preserving],
+      role: provider_role
+    )
+    expect(
+      Ast::Merge.resolve_provider(
+        provider_id: provider.provider_id,
+        family: :markdown,
+        dialect: provider_dialect,
+        backend: provider_backend,
+        profile_id: :source_preserving,
+        operation: :merge3
+      )
+    ).to equal(provider)
+  end
+
+  it 'analyzes unique parser-proven heading identities and emits JSON-ready results' do
+    result = provider.analyze(source: base)
+
+    expect(result).to include(ok: true)
+    expect(result.dig(:analysis, :owners).map { |owner| owner.fetch(:signature) }).to eq(
+      [[1, 'Alpha'], [1, 'Beta']]
+    )
+    expect { JSON.generate(Ast::Merge.json_ready(result)) }.not_to raise_error
+  end
+
+  it 'matches the shared safe-subset semantics at its explicit backend boundary' do
+    result = provider.analyze(source: "# One\n\nbody\n\n# Two\n\nbody\n")
+
+    expect(result.dig(:analysis, :backend)).to eq(provider_backend)
+    expect(result.dig(:analysis, :delegated_backend)).to eq(provider_backend)
+    expect(result.dig(:analysis, :owners).map { |owner| owner.fetch(:signature) }).to eq(
+      [[1, 'One'], [1, 'Two']]
+    )
+  end
+
+  it 'diffs and merges independent section edits, additions, and deletions' do
+    ours = base.sub('alpha', 'ours alpha')
+    theirs = base.sub("# Beta\n\nbeta\n", '')
+    deletion = provider.merge3(base_source: base, ours_source: ours, theirs_source: theirs)
+
+    addition_base = "#{base}\n"
+    ours_addition = "#{addition_base}# Ours\n\nours addition\n\n"
+    theirs_addition = "#{addition_base}# Theirs\n\ntheirs addition\n\n"
+    additions = provider.merge3(
+      base_source: addition_base,
+      ours_source: ours_addition,
+      theirs_source: theirs_addition
+    )
+    edit_diff = provider.diff2(before_source: base, after_source: ours)
+    addition_diff = provider.diff2(before_source: addition_base, after_source: ours_addition)
+
+    expect(edit_diff.fetch(:changes).map { |change| change.fetch(:change) }).to contain_exactly(:edited)
+    expect(addition_diff.fetch(:changes).map { |change| change.fetch(:change) }).to contain_exactly(:added)
+    expect(deletion).to include(ok: true)
+    expect(deletion.fetch(:output)).to include('ours alpha')
+    expect(deletion.fetch(:output)).not_to include('# Beta')
+    expect(additions).to include(ok: true)
+    expect(additions.fetch(:output)).to include('# Ours', '# Theirs')
+    expect(additions.fetch(:verification)).to include(
+      base_participated: true,
+      output_reparsed: true,
+      semantic_match: true,
+      byte_provenance_verified: true,
+      delegated_backend_verified: true,
+      backend: provider_backend
+    )
+  end
+
+  it 'localizes a same-section conflict to the parser-proven owner range' do
+    result = provider.merge3(
+      base_source: base,
+      ours_source: base.sub('alpha', 'ours'),
+      theirs_source: base.sub('alpha', 'theirs')
+    )
+
+    expect(result).to include(ok: false)
+    expect(result.fetch(:conflicts)).to contain_exactly(hash_including(category: :edit_edit))
+    expect(result.dig(:render_report, :strategy)).to eq(:section_localized_conflict)
+    expect(result.fetch(:conflicted_output)).to include('# Beta', 'beta')
+  end
+
+  it 'fails closed for duplicate, renamed, level-changed, nested, and headingless ownership' do
+    duplicate = "# Alpha\n\none\n\n# Alpha\n\ntwo\n"
+    expect(provider.analyze(source: duplicate)).to include(
+      ok: false,
+      diagnostics: include(hash_including(category: :ambiguous_owner))
+    )
+
+    {
+      rename: base.sub('# Alpha', '# Renamed'),
+      rename_with_body_edit: base.sub("# Alpha\n\nalpha", "# Renamed\n\nrewritten"),
+      level: base.sub('# Alpha', '## Alpha')
+    }.each_value do |ours|
+      result = provider.merge3(base_source: base, ours_source: ours, theirs_source: base.sub('beta', 'theirs'))
+      expect(result).to include(ok: false)
+      expect(result.fetch(:diagnostics)).to include(hash_including(blocking: true))
+      expect(result.dig(:render_report, :strategy)).to eq(:full_file_conflict)
+    end
+
+    expect(provider.analyze(source: "# Alpha\n\n## Nested\n\ntext\n")).to include(
+      ok: false,
+      diagnostics: include(hash_including(category: :unsafe_source_range))
+    )
+    expect(provider.analyze(source: "headingless prose\n")).to include(
+      ok: false,
+      diagnostics: include(hash_including(category: :unsafe_source_range))
+    )
+  end
+
+  it 'fails closed for setext headings and non-whitespace prose outside sections' do
+    expect(provider.analyze(source: "Alpha\n=====\n\ntext\n")).to include(
+      ok: false,
+      diagnostics: include(hash_including(category: :unsafe_source_range))
+    )
+    expect(provider.analyze(source: "preamble\n\n# Alpha\n\ntext\n")).to include(
+      ok: false,
+      diagnostics: include(hash_including(category: :unsafe_source_range))
+    )
+    expect(provider.analyze(source: "\n# Alpha\n\ntext\n")).to include(
+      ok: false,
+      diagnostics: include(hash_including(category: :unsafe_source_range))
+    )
+  end
+
+  it 'does not promote headings nested inside block containers to document section owners' do
+    quoted = "# Alpha\n\n> # Quoted\n> body\n\n# Beta\n\nbeta\n"
+    result = provider.analyze(source: quoted)
+
+    expect(result).to include(ok: true)
+    expect(result.dig(:analysis, :owners).map { |owner| owner.fetch(:signature) }).to eq(
+      [[1, 'Alpha'], [1, 'Beta']]
+    )
+  end
+
+  it 'cleanly composes independent deletions that remove every owned section' do
+    ours = "# Beta\n\nbeta\n"
+    theirs = "# Alpha\n\nalpha\n\n"
+    result = provider.merge3(base_source: base, ours_source: ours, theirs_source: theirs)
+
+    expect(result).to include(ok: true, output: '')
+    expect(result.fetch(:verification)).to include(
+      output_reparsed: true,
+      semantic_match: true,
+      planned_owner_count: 0,
+      output_owner_count: 0
+    )
+  end
+
+  it 'exactly preserves complex Markdown and a missing final newline for one-sided winners' do
+    exact = <<~'MARKDOWN'.chomp.sub('<HARD_BREAK>', '  ')
+      ---
+      title: Exact
+      ---
+      # Alpha
+
+      - list
+      - item
+      3. numbered
+      - [x] task
+
+      > quoted<HARD_BREAK>
+      > hard break &amp; \*escaped\*
+
+      ```ruby
+      puts "# not a heading"
+      ```
+
+      | a | b |
+      |---|---|
+      | 1 | 2 |
+
+      <div data-x='1'>inline HTML</div>
+
+      [ref]: https://example.test "Title"
+      [use][ref]
+
+      Footnote[^1].
+      [^1]: exact footnote
+
+      :::note
+      extension directive
+      :::
+    MARKDOWN
+    result = provider.merge3(base_source: base, ours_source: base, theirs_source: exact)
+
+    expect(result).to include(ok: true, output: exact)
+    expect(result.dig(:render_report, :strategy)).to eq(:exact_revision)
+    expect(result.fetch(:verification)).to include(byte_exact: true, semantic_match: true, base_participated: true)
+  end
+
+  it 'copies complex independently selected section fragments byte-for-byte in a composite' do
+    alpha = <<~'MARKDOWN'
+      # Alpha
+
+      - [ ] task
+      7. numbered
+
+      > quoted
+
+      ~~~~ruby extra
+      puts "&amp;"
+      ~~~~
+
+      | a | b |
+      |---|---|
+      | 1 | 2 |
+
+      <span data-x='1'>html</span>
+
+      [ref]: https://example.test
+      [use][ref] and footnote[^1].
+      [^1]: exact
+    MARKDOWN
+    beta = "# Beta\n\nbeta\n"
+    composite_base = "#{alpha}\n#{beta}"
+    ours_alpha = alpha.sub('- [ ] task', '- [x] task')
+    theirs_beta = beta.sub('beta', 'theirs')
+    result = provider.merge3(
+      base_source: composite_base,
+      ours_source: "#{ours_alpha}\n#{beta}",
+      theirs_source: "#{alpha}\n#{theirs_beta}"
+    )
+
+    expect(result).to include(ok: true, output: "#{ours_alpha}\n#{theirs_beta}")
+    expect(result.dig(:render_report, :provenance)).to all(include(copied_source: true))
+  end
+
+  it 'accepts parser-valid ambiguous exact winners with nonblocking diagnostics' do
+    duplicate = "# Same\n\none\n\n# Same\n\ntwo\n"
+    result = provider.merge3(base_source: base, ours_source: base, theirs_source: duplicate)
+
+    expect(result).to include(ok: true, output: duplicate)
+    expect(result.fetch(:diagnostics)).to include(
+      hash_including(category: :ambiguous_owner, blocking: false, source_role: :theirs)
+    )
+  end
+
+  it 'rejects malformed exact winners with selected-role attribution' do
+    malformed = "# Broken\0\n"
+    result = provider.merge3(base_source: base, ours_source: base, theirs_source: malformed)
+
+    expect(result).to include(ok: false, source_role: :theirs)
+    expect(result.fetch(:diagnostics)).to contain_exactly(
+      hash_including(category: :parse_error, blocking: true)
+    )
+  end
+
+  it 'uses the base in adversarial deletion merges' do
+    old_base = "# Obsolete\n\nold\n\n#{base}"
+    result = provider.merge3(base_source: old_base, ours_source: old_base, theirs_source: base)
+
+    expect(result).to include(ok: true, output: base)
+    expect(result.fetch(:output)).not_to include('Obsolete')
+    expect(result.dig(:verification, :base_participated)).to be(true)
+  end
+
+  it 'preserves standalone and legacy APIs' do
+    expect(legacy_assertion.call).to be(true)
+  end
+end
+# rubocop:enable Metrics/BlockLength