yaml-merge 7.1.6 → 7.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1d6e4b41e159981a900735e298bfe8091566e9c639ce4f394a6528718659484
-  data.tar.gz: '003499bdb2ece6e5022aed479b61f0655574b451df095f2fc465275030d1d2d9'
+  metadata.gz: a4fc343ed5a3cdb282f7e215a62d0754a4b0e1908959582f09f871af039771f2
+  data.tar.gz: 39f6895dc4d2066f488437744156357ad40cdfb2334030bc37ed652e6c7a2b56
 SHA512:
-  metadata.gz: ecf5a8c23fb8458021586437968824c11263b0dfb823c58ebd6718d19c5fa2b7ea812f5a3874bd85659933b139ef114d5c05ea1b05b1c15ff6c703a2eae41595
-  data.tar.gz: 8a9abe6a47707384e1f0c3ef5b34791c3ce9eeb81f7f01f8347839fc0d4b4d0842f91b09a3733b7af5d3b0f19126fa97402035172f90a6057aa180fc73052445
+  metadata.gz: 077125af08b9a5547bbd434776db9ca73f0d88fd706583bb1d296e213b77456ab1760abd0cca5f6b060dc87b735becc1963b49d28bcf6a4ae8de90d78a54d16c
+  data.tar.gz: 197d2a7cbc7d0dda453d1ab1676ca4e91013c6f74f8378e23113376d7c66a3269be3544373df6be5e62d88cbad8b152a94658a22838e8c4485ab6889ec39f316

data/README.md

@@ -22,8 +22,9 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 ## 🌻 Synopsis <a href="https://discord.gg/3qme4XHNKN"><img alt="Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0" src="https://logos.galtzo.com/assets/images/galtzo-floss/avatar-128px.svg" width="8%" align="right"/></a> <a href="https://ruby-toolbox.com"><img alt="ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5" src="https://logos.galtzo.com/assets/images/ruby-lang/avatar-128px.svg" width="8%" align="right"/></a>
 
 `Yaml::Merge` is the canonical YAML family package. It is the YAML substrate for
-StructuredMerge Ruby: it registers the tree-sitter YAML path and should own the
-shared YAML merge behavior used by provider implementations. YAML parsing and
+StructuredMerge Ruby: it registers the TSLP YAML path and owns the shared
+source-preserving provider behavior used by parser-specific implementations.
+YAML parsing and
 backend selection enter through `tree_haver`; source-preserving
 partial document insertion, replacement, and removal should enter through
 `ast-crispr`; merge orchestration should use `ast-merge`.
@@ -39,6 +40,7 @@ Hash/Array round-trips.
 - Backend feature profiles for the shared language-pack parser.
 - Path-based owner matching for mapping entries.
 - Shared YAML-family merge semantics for provider gems.
+- A TSLP workflow provider and a reusable provider engine for native parsers.
 - Destination-wins array policy.
 - Hash result API for fixture runners and higher-level tools.
 

data/lib/yaml/merge/provider.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Yaml
+  # YAML workflow provider integration.
+  module Merge
+    # TSLP projection for the shared YAML source-preserving provider.
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- tree-sitter YAML validation and projection remain one adapter boundary
+    class Provider < SourcePreservingProvider
+      PROVIDER_ID = 'ruby.yaml'
+      BACKEND = BACKEND_REFERENCE
+      PACKAGE_NAME = Merge::PACKAGE_NAME
+      PACKAGE_VERSION = Version::VERSION
+      ROLE = :workflow
+
+      private
+
+      def analyze_role(role, source)
+        analysis = TreeHaver.with_backend(backend_id) { FileAnalysis.new(source) }
+        return invalid_analysis(role, source, analysis) unless analysis.valid?
+
+        documents = analysis.documents
+        issues = []
+        issues << issue(:multiple_documents, 'YAML input must contain exactly one document') unless documents.one?
+        document = documents.first
+        root = document&.body_node
+        issues << issue(:non_mapping_root, 'YAML document root must be a mapping') unless root&.mapping?
+        issues.concat(node_issues(root)) if root
+
+        parsed = Yaml::Merge.parse_yaml(source, 'yaml', backend: backend_id)
+        unless parsed[:ok]
+          diagnostic = parsed.fetch(:diagnostics).first || {}
+          return invalid_document(role, source, diagnostic[:category] || :parse_error, diagnostic[:message])
+        end
+
+        entries = root&.mapping? ? mapping_entries(analysis, root, parsed.dig(:analysis, :document), source, role) : []
+        duplicate = entries.group_by(&:key).find { |_key, matches| matches.length > 1 }
+        issues << issue(:duplicate_key, "Duplicate YAML key #{duplicate.first}", key: duplicate.first) if duplicate
+
+        Document.new(
+          role: role,
+          source: source,
+          analysis: analysis,
+          entries: entries.freeze,
+          by_key: entries.to_h { |entry| [entry.key, entry] }.freeze,
+          issues: issues.uniq.freeze,
+          document_attributes: document ? node_attributes(document) : {}
+        )
+      rescue TreeHaver::Error => e
+        invalid_document(role, source, :parse_error, e.message)
+      rescue StandardError => e
+        invalid_document(role, source, :structural_error, e.message)
+      end
+
+      def invalid_analysis(role, source, analysis)
+        message = analysis.errors.map(&:to_s).join('; ')
+        invalid_document(role, source, :parse_error, message.empty? ? 'YAML parse failed' : message)
+      end
+
+      def node_issues(root)
+        issues = []
+        walk_nodes(root.node) do |node|
+          type = node.type.to_s
+          issues << issue(:alias, 'YAML aliases require an exact one-sided merge') if type == 'alias'
+          issues << issue(:anchor, 'YAML anchors require an exact one-sided merge') if type == 'anchor'
+          issues << issue(:directive, 'YAML directives require an exact one-sided merge') if type.include?('directive')
+          if %w[flow_mapping flow_sequence].include?(type)
+            issues << issue(:flow_collection, 'Flow-style collections require an exact one-sided merge')
+          end
+        end
+        issues.uniq.freeze
+      end
+
+      def walk_nodes(node, &block)
+        yield node
+        node.children.each { |child| walk_nodes(child, &block) }
+      end
+
+      def mapping_entries(analysis, root, semantic_document, source, role)
+        root.mapping_pairs.filter_map.with_index do |pair, index|
+          key = pair.key_name
+          next invalid_top_level_entry(pair, source, role, index) unless key
+
+          build_entry(analysis, pair, key, semantic_document[key], source, role, index)
+        end
+      end
+
+      def invalid_top_level_entry(pair, source, role, index)
+        Entry.new(
+          key: "<complex-key-#{index}>",
+          start_line: pair.start_line,
+          end_line: pair.end_line,
+          fragment: source_lines(source, pair.start_line, pair.end_line),
+          semantic: nil,
+          attributes: node_attributes(pair.value_node),
+          role: role,
+          ownership_provable: false
+        )
+      end
+
+      def build_entry(analysis, pair, key, semantic, source, role, index)
+        key_line = pair.start_line
+        value_end = pair.end_line
+        leading_start = owned_leading_start(analysis, pair, index, key_line)
+        Entry.new(
+          key: key,
+          start_line: leading_start,
+          end_line: value_end,
+          fragment: source_lines(source, leading_start, value_end),
+          semantic: semantic,
+          attributes: node_attributes(pair.value_node),
+          role: role,
+          ownership_provable: ownership_provable?(analysis, pair, index, key_line, leading_start)
+        )
+      end
+
+      def owned_leading_start(analysis, pair, index, key_line)
+        return key_line if index.zero?
+
+        region = analysis.comment_attachment_for(pair)&.leading_region
+        return key_line unless region && region.end_line == key_line - 1
+        return key_line if region.metadata[:floating]
+
+        region.start_line
+      end
+
+      def ownership_provable?(analysis, pair, index, key_line, leading_start)
+        return true if leading_start == key_line
+        return false if index.zero?
+
+        region = analysis.comment_attachment_for(pair)&.leading_region
+        region && !region.metadata[:floating] && region.start_line == leading_start
+      end
+
+      def node_attributes(node)
+        return {} unless node
+
+        {
+          type: node.type.to_s,
+          canonical_type: node.type.to_s,
+          signature: public_value(node.signature),
+          children: node.semantic_children.map do |child|
+            node_attributes(NodeWrapper.new(child, lines: node.lines, source: node.source))
+          end
+        }
+      end
+
+      def public_value(value)
+        case value
+        when Array then value.map { |item| public_value(item) }
+        when Hash then value.to_h { |key, item| [key.to_s, public_value(item)] }
+        when String, Integer, Float, TrueClass, FalseClass, NilClass then value
+        else value.to_s
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+
+    class << self
+      def merge_provider
+        @merge_provider ||= Provider.new
+      end
+
+      def register_provider!(replace: false)
+        Ast::Merge.register_provider(merge_provider, replace: replace)
+      end
+    end
+  end
+end

data/lib/yaml/merge/smart_merger.rb

@@ -125,7 +125,7 @@ module Yaml
 
         def merge_matched_nodes(template_node, dest_node, template_analysis, dest_analysis, template_owners: nil,
                                 dest_owners: nil, template_boundary_line: nil, dest_boundary_line: nil)
-          if template_node.document? && dest_node.document?
+          if node_kind?(template_node, :document?) && node_kind?(dest_node, :document?)
             dest_header_end = emit_document_header(dest_node, dest_analysis)
             template_header_end = document_header_end_line(template_node)
             merge_node_lists(
@@ -136,12 +136,12 @@ module Yaml
               template_boundary_line: template_header_end,
               dest_boundary_line: dest_header_end
             )
-          elsif template_node.mapping_pair? && dest_node.mapping_pair?
+          elsif node_kind?(template_node, :mapping_pair?) && node_kind?(dest_node, :mapping_pair?)
             merge_mapping_pair(template_node, dest_node, template_analysis, dest_analysis, template_owners: template_owners,
                                                                                            dest_owners: dest_owners,
                                                                                            template_boundary_line: template_boundary_line,
                                                                                            dest_boundary_line: dest_boundary_line)
-          elsif template_node.mapping? && dest_node.mapping?
+          elsif node_kind?(template_node, :mapping?) && node_kind?(dest_node, :mapping?)
             merge_node_lists(
               template_node.mergeable_children,
               dest_node.mergeable_children,
@@ -167,6 +167,10 @@ module Yaml
           end
         end
 
+        def node_kind?(node, predicate)
+          node.respond_to?(predicate) && node.public_send(predicate)
+        end
+
         def merge_mapping_pair(template_node, dest_node, template_analysis, dest_analysis, template_owners: nil,
                                dest_owners: nil, template_boundary_line: nil, dest_boundary_line: nil)
           template_value = template_node.value_node&.unwrap_value_node

data/lib/yaml/merge/source_preserving_provider.rb

@@ -0,0 +1,799 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Yaml
+  # Parser-neutral YAML structural merge provider integration.
+  module Merge
+    # Conservative source-preserving provider for top-level YAML mappings.
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- provider validation, planning, rendering, and verification form one safety boundary
+    class SourcePreservingProvider
+      DEFAULT_PROFILE = :source_preserving
+      DIALECTS = %i[yaml].freeze
+
+      Entry = Data.define(
+        :key,
+        :start_line,
+        :end_line,
+        :fragment,
+        :semantic,
+        :attributes,
+        :role,
+        :ownership_provable
+      )
+      Document = Data.define(
+        :role,
+        :source,
+        :analysis,
+        :entries,
+        :by_key,
+        :issues,
+        :document_attributes
+      )
+      Decision = Data.define(:key, :base, :ours, :theirs, :selected_role, :classification, :conflict)
+
+      def provider_id = self.class::PROVIDER_ID
+      def family = 'yaml'
+      def backend_reference = self.class::BACKEND
+      def backend_id = backend_reference.id.to_sym
+      def package_name = self.class::PACKAGE_NAME
+      def package_version = self.class::PACKAGE_VERSION
+      def role = self.class.const_defined?(:ROLE, false) ? self.class::ROLE : :backend
+
+      def capabilities
+        {
+          operations: Ast::Merge::ProviderContract::OPERATIONS,
+          dialects: DIALECTS,
+          backends: [backend_id],
+          profiles: [DEFAULT_PROFILE],
+          role: role,
+          source_preservation: %i[
+            exact_source
+            mapping_entry_fragments
+            comment_ownership
+            line_provenance
+            reparse
+            semantic_verification
+            ast_attribute_verification
+          ]
+        }.freeze
+      end
+
+      def analyze(request)
+        document = analyze_role(:source, request.fetch(:source))
+        return invalid_document_failure(:analyze, request, [document]) unless document.issues.empty?
+
+        result(
+          :analyze,
+          request,
+          analysis: analysis_payload(document),
+          extensions: analysis_extensions(document),
+          verification: { source_parsed: true, structurally_unambiguous: true }
+        )
+      end
+
+      def diff2(request)
+        before = analyze_role(:before, request.fetch(:before_source))
+        after = analyze_role(:after, request.fetch(:after_source))
+        unsafe = [before, after].reject { |document| document.issues.empty? }
+        return invalid_document_failure(:diff2, request, unsafe) unless unsafe.empty?
+
+        changes = mapping_changes(before, after)
+        result(
+          :diff2,
+          request,
+          diff: { before: analysis_payload(before), after: analysis_payload(after), changes: changes },
+          changes: changes,
+          verification: { before_parsed: true, after_parsed: true }
+        )
+      end
+
+      def merge2(request)
+        documents = {
+          incoming: analyze_role(:incoming, request.fetch(:incoming_source)),
+          current: analyze_role(:current, request.fetch(:current_source))
+        }
+        unsafe = documents.values.reject { |document| document.issues.empty? }
+        return invalid_document_failure(:merge2, request, unsafe) unless unsafe.empty?
+        return render_exact_merge2(request, documents) if documents[:incoming].source == documents[:current].source
+
+        merged = recursive_merge2(documents)
+        rendered = render_recursive_merge2(request, documents, merged)
+        verification = verify_recursive_merge2(rendered, documents)
+        return verification_failure(:merge2, request, rendered, [], verification) unless verification[:semantic_match]
+
+        result(
+          :merge2,
+          request,
+          output: rendered.content,
+          changes: mapping_changes(documents[:current], analyze_role(:output, rendered.content)),
+          render_report: render_report(rendered, :recursive_mapping_composite),
+          verification: verification
+        )
+      end
+
+      def merge3(request)
+        documents = %i[base ours theirs].to_h do |role|
+          [role, analyze_role(role, request.fetch(:"#{role}_source"))]
+        end
+        exact_role = exact_revision_role(documents)
+        return render_exact(request, documents, exact_role) if exact_role
+
+        unsafe = documents.values.reject { |document| document.issues.empty? }
+        return structural_conflict(request, documents, unsafe) unless unsafe.empty?
+        return unmanaged_conflict(request, documents) unless unmanaged_unchanged?(documents)
+
+        decisions = three_way_decisions(documents)
+        conflicts = decisions.select(&:conflict)
+        return render_conflicts(request, documents, decisions, conflicts) unless conflicts.empty?
+
+        render_composite(request, documents, decisions)
+      end
+
+      private
+
+      def analyze_role(_role, _source)
+        raise NotImplementedError, "#{self.class} must implement #analyze_role"
+      end
+
+      def invalid_document(role, source, category, message)
+        Document.new(
+          role: role,
+          source: source,
+          analysis: nil,
+          entries: [].freeze,
+          by_key: {}.freeze,
+          issues: [issue(category, message)].freeze,
+          document_attributes: {}
+        )
+      end
+
+      def analysis_payload(document)
+        {
+          dialect: 'yaml',
+          backend: backend_id.to_s,
+          document_attributes: document.document_attributes,
+          entries: document.entries.map do |entry|
+            {
+              key: entry.key,
+              value: entry.semantic,
+              attributes: entry.attributes,
+              source_lines: [entry.start_line, entry.end_line]
+            }
+          end,
+          structurally_unambiguous: document.issues.empty?
+        }
+      end
+
+      def analysis_extensions(_document)
+        []
+      end
+
+      def render_exact_merge2(request, documents)
+        current = documents.fetch(:current)
+        rendered = render_plan(request, [whole_source_fragment(:ours, current.source)])
+        verification = verify_exact(rendered.content, current, :current)
+        result(
+          :merge2,
+          request,
+          output: rendered.content,
+          changes: [],
+          render_report: render_report(rendered, :exact_revision),
+          verification: verification
+        )
+      end
+
+      def recursive_merge2(documents)
+        result = MergeResult.new(
+          template_analysis: documents[:incoming].analysis,
+          dest_analysis: documents[:current].analysis
+        )
+        SmartMerger::Resolver.new(
+          documents[:incoming].analysis,
+          documents[:current].analysis,
+          preference: :destination,
+          add_template_only_nodes: true,
+          merge_sequences: false
+        ).resolve(result)
+        result
+      end
+
+      def render_recursive_merge2(request, documents, merged)
+        fragments = merged.lines.map do |line|
+          recursive_merge2_line_fragment(line, documents)
+        end
+        render_plan(request, fragments)
+      end
+
+      def recursive_merge2_line_fragment(line, documents)
+        role = line.fetch(:source) == :template ? :theirs : :ours
+        original_line = line[:original_line]
+        content = "#{line.fetch(:content)}\n"
+        source = documents.fetch(role == :theirs ? :incoming : :current).source
+        if original_line && source.lines[original_line - 1] == content
+          return range_fragment(role, original_line, original_line)
+        end
+
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: content,
+          reason: :structured_emitter_line,
+          producer: provider_id,
+          metadata: { source_role: role, original_line: original_line }.compact
+        )
+      end
+
+      def verify_recursive_merge2(rendered, documents)
+        parsed = analyze_role(:output, rendered.content)
+        expected = Yaml::Merge.send(
+          :merge_yaml_mappings,
+          document_semantics(documents[:incoming]),
+          document_semantics(documents[:current])
+        )
+        actual = document_semantics(parsed)
+        {
+          output_reparsed: true,
+          semantic_match: parsed.issues.empty? && actual == expected,
+          ast_attributes_match: parsed.issues.empty?,
+          source_match: rendered.synthesized_fragments.empty?,
+          ordered_entries: actual.to_a,
+          line_sources: rendered.line_records.map { |record| record.slice(:source_role, :original_line) }
+        }
+      end
+
+      def document_semantics(document)
+        document.entries.to_h { |entry| [entry.key, entry.semantic] }
+      end
+
+      def entry_state(entry)
+        entry && [entry.semantic, entry.attributes, entry.fragment]
+      end
+
+      def exact_revision_role(documents)
+        return :ours if documents[:ours].source == documents[:theirs].source
+        return :ours if documents[:base].source == documents[:theirs].source
+
+        :theirs if documents[:base].source == documents[:ours].source
+      end
+
+      def render_exact(request, documents, role)
+        winner = documents.fetch(role)
+        return structural_conflict(request, documents, [winner]) unless fatal_issues(winner).empty?
+
+        rendered = render_plan(request, [whole_source_fragment(role, winner.source)])
+        verification = verify_exact(rendered.content, winner, role)
+        return verification_failure(:merge3, request, rendered, [], verification) unless verification[:semantic_match]
+
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: mapping_changes(documents[:base], winner),
+          diagnostics: diagnostics_for(*documents.values),
+          render_report: render_report(rendered, :exact_revision),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def verify_exact(output, expected, role)
+        parsed = analyze_role(:output, output)
+        {
+          output_reparsed: true,
+          byte_exact: output == expected.source,
+          source_match: output == expected.source,
+          semantic_match: fatal_issues(parsed).empty? && document_signature(parsed) == document_signature(expected),
+          ast_attributes_match: parsed.document_attributes == expected.document_attributes &&
+            parsed.entries.map(&:attributes) == expected.entries.map(&:attributes),
+          ordered_entries: ordered_semantics(parsed),
+          source_role: role
+        }
+      end
+
+      def mapping_changes(before, after)
+        ordered_keys(before, after).filter_map do |key|
+          left = before.by_key[key]
+          right = after.by_key[key]
+          next if semantic_entry_state(left) == semantic_entry_state(right)
+
+          { path: "/#{key}", ours: :unchanged, theirs: change_kind(left, right) }.freeze
+        end.freeze
+      end
+
+      def semantic_entry_state(entry)
+        entry && [entry.semantic, entry.attributes]
+      end
+
+      def ordered_keys(*documents)
+        documents.flat_map { |document| document.entries.map(&:key) }.uniq
+      end
+
+      def change_kind(before, after)
+        return :added unless before
+        return :deleted unless after
+
+        :edited
+      end
+
+      def three_way_decisions(documents)
+        ordered_keys(documents[:ours], documents[:theirs], documents[:base]).map do |key|
+          base = documents[:base].by_key[key]
+          ours = documents[:ours].by_key[key]
+          theirs = documents[:theirs].by_key[key]
+          selected_role =
+            if entry_state(ours) == entry_state(theirs)
+              :ours
+            elsif entry_state(ours) == entry_state(base)
+              :theirs
+            elsif entry_state(theirs) == entry_state(base)
+              :ours
+            end
+          classification = {
+            path: "/#{key}",
+            ours: side_change(base, ours),
+            theirs: side_change(base, theirs)
+          }.freeze
+          Decision.new(
+            key: key,
+            base: base,
+            ours: ours,
+            theirs: theirs,
+            selected_role: selected_role,
+            classification: classification,
+            conflict: selected_role.nil?
+          )
+        end.freeze
+      end
+
+      def side_change(base, side)
+        entry_state(base) == entry_state(side) ? :unchanged : change_kind(base, side)
+      end
+
+      def unmanaged_unchanged?(documents)
+        anchor_keys = documents.values.map { |document| document.by_key.keys }.reduce(&:intersection)
+        signatures = documents.transform_values { |document| unmanaged_signature(document, anchor_keys) }
+        signatures[:base] == signatures[:ours] && signatures[:base] == signatures[:theirs]
+      end
+
+      def unmanaged_signature(document, anchor_keys)
+        entries = document.entries.sort_by(&:start_line)
+        signature = []
+        cursor = 1
+        entries.each do |entry|
+          if cursor < entry.start_line
+            signature << [:source, source_lines(document.source, cursor, entry.start_line - 1)]
+          end
+          signature << [:entry, entry.key] if anchor_keys.include?(entry.key)
+          cursor = entry.end_line + 1
+        end
+        signature << [:source, source_lines(document.source, cursor, document.source.lines.length)]
+        signature
+      end
+
+      def render_composite(request, documents, decisions)
+        by_key = decisions.to_h { |decision| [decision.key, decision] }
+        fragments = []
+        selected = []
+        cursor = 1
+        documents[:ours].entries.sort_by(&:start_line).each do |ours_entry|
+          fragments << range_fragment(:ours, cursor, ours_entry.start_line - 1) if cursor < ours_entry.start_line
+          decision = by_key.fetch(ours_entry.key)
+          selected_entry_value = decision.selected_role && decision.public_send(decision.selected_role)
+          if selected_entry_value
+            fragments << entry_fragment(decision.selected_role, selected_entry_value)
+            selected << selected_entry(selected_entry_value, decision.selected_role)
+          end
+          cursor = ours_entry.end_line + 1
+        end
+        ours_line_count = documents[:ours].source.lines.length
+        fragments << range_fragment(:ours, cursor, ours_line_count) if cursor <= ours_line_count
+        decisions.each do |decision|
+          next if decision.ours || decision.selected_role != :theirs || !decision.theirs
+
+          fragments << entry_fragment(:theirs, decision.theirs)
+          selected << selected_entry(decision.theirs, :theirs)
+        end
+
+        rendered = render_plan(request, separated_fragments(fragments.compact, documents))
+        verification = verify_composite(rendered.content, selected)
+        unless verification[:semantic_match]
+          return verification_failure(:merge3, request, rendered, decisions, verification)
+        end
+
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: decisions.map(&:classification),
+          render_report: render_report(rendered, :exact_mapping_entry_composite),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def selected_entry(entry, role)
+        {
+          key: entry.key,
+          semantic: entry.semantic,
+          attributes: entry.attributes,
+          source_role: role,
+          source_lines: [entry.start_line, entry.end_line],
+          fragment: entry.fragment
+        }.freeze
+      end
+
+      def verify_composite(output, selected)
+        parsed = analyze_role(:output, output)
+        expected_semantics = selected.map { |entry| [entry[:key], entry[:semantic]] }
+        expected_attributes = selected.map { |entry| [entry[:key], entry[:attributes]] }
+        actual_semantics = parsed.entries.map { |entry| [entry.key, entry.semantic] }
+        actual_attributes = parsed.entries.map { |entry| [entry.key, entry.attributes] }
+        source_match = parsed.entries.zip(selected).all? do |actual, expected|
+          actual.fragment == expected[:fragment] ||
+            (!expected[:fragment].end_with?("\n") && actual.fragment == "#{expected[:fragment]}\n")
+        end
+        {
+          output_reparsed: true,
+          semantic_match: parsed.issues.empty? && actual_semantics == expected_semantics &&
+            actual_attributes == expected_attributes && source_match,
+          ast_attributes_match: actual_attributes == expected_attributes,
+          source_match: source_match,
+          ordered_entries: actual_semantics,
+          entry_sources: selected.map { |entry| entry.slice(:key, :source_role, :source_lines) }
+        }
+      end
+
+      def ordered_semantics(document)
+        document.entries.map { |entry| [entry.key, entry.semantic] }
+      end
+
+      def document_signature(document)
+        [ordered_semantics(document), document.entries.map(&:attributes)]
+      end
+
+      def fatal_issues(document)
+        document.issues.select { |item| %i[parse_error structural_error].include?(item[:category]) }
+      end
+
+      def render_conflicts(request, documents, decisions, conflicts)
+        unless conflicts.all? { |conflict| conflict.ours&.ownership_provable }
+          return full_file_conflict(request, documents, decisions, conflicts, :ownership_unproven)
+        end
+        unless unmanaged_unchanged?(documents)
+          return full_file_conflict(request, documents, decisions, conflicts, :unmanaged_source_change)
+        end
+
+        by_key = conflicts.to_h { |conflict| [conflict.key, conflict] }
+        fragments = []
+        cursor = 1
+        documents[:ours].entries.sort_by(&:start_line).each do |entry|
+          fragments << range_fragment(:ours, cursor, entry.start_line - 1) if cursor < entry.start_line
+          conflict = by_key[entry.key]
+          fragments << (conflict ? conflict_fragment(request, conflict) : entry_fragment(:ours, entry))
+          cursor = entry.end_line + 1
+        end
+        ours_line_count = documents[:ours].source.lines.length
+        fragments << range_fragment(:ours, cursor, ours_line_count) if cursor <= ours_line_count
+        rendered = render_plan(request, fragments.compact)
+        conflict_failure(request, decisions, conflicts, rendered, :mapping_entry_localized_conflict)
+      end
+
+      def conflict_fragment(request, decision)
+        Ast::Merge::SourceRender::ConflictFragment.new(
+          conflict_id: conflict_id(decision.key),
+          base: conflict_side(:base, decision.base),
+          ours: conflict_side(:ours, decision.ours),
+          theirs: conflict_side(:theirs, decision.theirs),
+          labels: request.fetch(:labels, {}),
+          marker_size: request.fetch(:conflict_marker_size, 7),
+          metadata: { path: decision.classification[:path], category: conflict_category(decision) }
+        )
+      end
+
+      def conflict_side(role, entry)
+        return [] unless entry
+
+        [entry_fragment(role, entry, line_bounded: true)]
+      end
+
+      def conflict_category(decision)
+        decision.ours.nil? || decision.theirs.nil? ? :delete_edit : :edit_edit
+      end
+
+      def conflict_id(key)
+        "yaml-mapping-#{Digest::SHA256.hexdigest(key)[0, 16]}"
+      end
+
+      def conflict_failure(request, decisions, conflicts, rendered, strategy)
+        failure(
+          :merge3,
+          request,
+          category: :merge_conflict,
+          message: 'YAML mapping entries changed incompatibly.',
+          changes: decisions.map(&:classification),
+          conflicts: conflicts.map { |decision| conflict_payload(decision) },
+          conflicted_output: rendered.content,
+          conflicted_source: rendered.content,
+          render_report: render_report(rendered, strategy),
+          verification: { base_participated: true }
+        )
+      end
+
+      def structural_conflict(request, documents, unsafe)
+        source_role = unsafe.first.role
+        full_file_conflict(
+          request,
+          documents,
+          safe_decisions(documents),
+          [],
+          :structural_ambiguity,
+          diagnostics: [
+            {
+              category: unsafe.first.issues.first[:category],
+              severity: :error,
+              message: "#{source_role} YAML input is unsafe for structural merge.",
+              blocking: true,
+              source_role: source_role
+            },
+            *diagnostics_for(*unsafe)
+          ]
+        )
+      end
+
+      def safe_decisions(documents)
+        return [] unless documents.values.all? { |document| document.issues.empty? }
+
+        three_way_decisions(documents)
+      end
+
+      def unmanaged_conflict(request, documents)
+        full_file_conflict(
+          request,
+          documents,
+          three_way_decisions(documents),
+          [],
+          :unmanaged_source_change,
+          diagnostics: [{
+            category: :unmanaged_source_change,
+            severity: :error,
+            message: 'Unmanaged YAML layout or comments changed independently.',
+            blocking: true
+          }]
+        )
+      end
+
+      def full_file_conflict(request, documents, decisions, conflicts, reason, diagnostics: nil)
+        conflict = { conflict_id: 'yaml-conflict-root', category: reason, path: '<document>' }.freeze
+        rendered = render_plan(
+          request,
+          [
+            Ast::Merge::SourceRender::ConflictFragment.new(
+              conflict_id: conflict[:conflict_id],
+              base: conflict_source(:base, documents[:base].source),
+              ours: conflict_source(:ours, documents[:ours].source),
+              theirs: conflict_source(:theirs, documents[:theirs].source),
+              labels: request.fetch(:labels, {}),
+              marker_size: request.fetch(:conflict_marker_size, 7),
+              metadata: { category: reason }
+            )
+          ]
+        )
+        failure(
+          :merge3,
+          request,
+          category: reason,
+          message: 'YAML source cannot be safely combined structurally.',
+          diagnostics: diagnostics,
+          changes: decisions.map(&:classification),
+          conflicts: conflicts.empty? ? [conflict] : conflicts.map { |item| conflict_payload(item) },
+          fallbacks: [{ from: :mapping_entry_composite, to: :full_file_conflict, reason: reason }],
+          conflicted_output: rendered.content,
+          conflicted_source: rendered.content,
+          render_report: render_report(rendered, :full_file_conflict),
+          verification: { base_participated: true },
+          source_role: diagnostics&.first&.fetch(:source_role, nil)
+        )
+      end
+
+      def conflict_payload(decision)
+        {
+          conflict_id: conflict_id(decision.key),
+          category: conflict_category(decision),
+          path: decision.classification[:path],
+          change_classification: decision.classification
+        }.freeze
+      end
+
+      def conflict_source(role, source)
+        return [] if source.empty?
+
+        [whole_source_fragment(role, source, line_bounded: true)]
+      end
+
+      def separated_fragments(fragments, documents)
+        fragments.each_with_index.flat_map do |fragment, index|
+          next [fragment] if index == fragments.length - 1
+          next [fragment] if fragment.is_a?(Ast::Merge::SourceRender::ConflictFragment)
+
+          content = fragment_content(fragment, documents)
+          next [fragment] if content.empty? || content.end_with?("\n")
+
+          [
+            Ast::Merge::SourceRender::SynthesizedFragment.new(
+              content: "#{content}\n",
+              reason: :mapping_entry_separator,
+              producer: provider_id,
+              metadata: fragment.metadata.merge(copied_source: true)
+            )
+          ]
+        end
+      end
+
+      def fragment_content(fragment, documents)
+        return fragment.content if fragment.is_a?(Ast::Merge::SourceRender::SynthesizedFragment)
+
+        document = documents.fetch(fragment.revision)
+        source_lines(document.source, fragment.start_line, fragment.end_line)
+      end
+
+      def whole_source_fragment(role, source, line_bounded: false)
+        if source.empty?
+          return Ast::Merge::SourceRender::SynthesizedFragment.new(
+            content: '',
+            reason: :exact_empty_source,
+            producer: provider_id,
+            metadata: { source_role: role }
+          )
+        end
+        fragment = range_fragment(role, 1, source.lines.length)
+        return fragment unless line_bounded && !source.end_with?("\n")
+
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: "#{source}\n",
+          reason: :conflict_line_boundary,
+          producer: provider_id,
+          metadata: { source_role: role, copied_source: true }
+        )
+      end
+
+      def entry_fragment(role, entry, line_bounded: false)
+        unless line_bounded && !entry.fragment.end_with?("\n")
+          return range_fragment(role, entry.start_line, entry.end_line, yaml_key: entry.key)
+        end
+
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: "#{entry.fragment}\n",
+          reason: :conflict_line_boundary,
+          producer: provider_id,
+          metadata: { source_role: role, yaml_key: entry.key, copied_source: true }
+        )
+      end
+
+      def range_fragment(role, start_line, end_line, **metadata)
+        return if end_line < start_line
+
+        Ast::Merge::SourceRender::SourceFragment.new(
+          revision: role,
+          start_line: start_line,
+          end_line: end_line,
+          metadata: { source_role: role }.merge(metadata)
+        )
+      end
+
+      def source_lines(source, start_line, end_line)
+        return '' if end_line < start_line
+
+        source.lines.slice(start_line - 1, end_line - start_line + 1).to_a.join
+      end
+
+      def render_plan(request, fragments)
+        Ast::Merge::SourceRender::Renderer.new.render(
+          Ast::Merge::SourceRender::Plan.new(
+            sources: {
+              base: request[:base_source].to_s,
+              ours: request[:ours_source] || request[:current_source].to_s,
+              theirs: request[:theirs_source] || request[:incoming_source].to_s
+            },
+            fragments: fragments,
+            metadata: { provider_id: provider_id }
+          )
+        )
+      end
+
+      def render_report(rendered, strategy)
+        {
+          strategy: strategy,
+          line_records: rendered.line_records,
+          synthesized_fragments: rendered.synthesized_fragments,
+          conflicts: rendered.conflicts,
+          verification_input: rendered.verification_input
+        }
+      end
+
+      def issue(category, message, **metadata)
+        { category: category, message: message, **metadata }.freeze
+      end
+
+      def diagnostics_for(*documents)
+        documents.flat_map do |document|
+          document.issues.map do |item|
+            item.merge(severity: :warning, blocking: false, source_role: document.role).freeze
+          end
+        end.freeze
+      end
+
+      def invalid_document_failure(operation, request, documents)
+        first = documents.first
+        failure(
+          operation,
+          request,
+          category: first.issues.first[:category],
+          message: "#{first.role} YAML input is unsafe",
+          diagnostics: diagnostics_for(*documents).map { |diagnostic| diagnostic.merge(blocking: true) },
+          source_role: first.role
+        )
+      end
+
+      def verification_failure(operation, request, rendered, decisions, verification)
+        failure(
+          operation,
+          request,
+          category: :verification_failure,
+          message: 'Rendered YAML did not preserve planned ordered semantics, AST attributes, and source fragments.',
+          changes: decisions.map(&:classification),
+          render_report: render_report(rendered, :exact_mapping_entry_composite),
+          verification: operation == :merge3 ? verification.merge(base_participated: true) : verification
+        )
+      end
+
+      def result(operation, request, diagnostics: [], changes: [], conflicts: [], fallbacks: [],
+                 render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: true,
+          envelope: envelope(
+            request,
+            diagnostics: diagnostics,
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def failure(operation, request, category:, message:, diagnostics: nil, changes: [], conflicts: [],
+                  fallbacks: [], render_report: {}, verification: {}, **payload)
+        diagnostics ||= [{ category: category, severity: :error, message: message, blocking: true }]
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: false,
+          envelope: envelope(
+            request,
+            diagnostics: diagnostics,
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def envelope(request, **fields)
+        {
+          provider: {
+            provider_id: provider_id,
+            family: family,
+            dialect: request[:dialect] || :yaml,
+            backend: request[:backend] || backend_id,
+            package: package_name,
+            package_version: package_version
+          },
+          profile: { profile_id: request[:profile_id] || DEFAULT_PROFILE }
+        }.merge(fields)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+  end
+end

data/lib/yaml/merge/version.rb

@@ -5,7 +5,7 @@ module Yaml
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = '7.1.6'
+      VERSION = '7.1.8'
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/yaml/merge.rb

@@ -45,6 +45,8 @@ module Yaml
     autoload :MergeResult, 'yaml/merge/merge_result'
     autoload :NodeWrapper, 'yaml/merge/node_wrapper'
     autoload :SmartMerger, 'yaml/merge/smart_merger'
+    autoload :SourcePreservingProvider, 'yaml/merge/source_preserving_provider'
+    autoload :Provider, 'yaml/merge/provider'
 
     module_function
 
@@ -589,3 +591,5 @@ module Yaml
 end
 
 Yaml::Merge.register_backend!
+require_relative 'merge/provider'
+Yaml::Merge.register_provider!

data/sig/yaml/merge.rbs

@@ -1,5 +1,21 @@
 module Yaml
   module Merge
+    class SourcePreservingProvider
+      def provider_id: () -> String
+      def family: () -> String
+      def capabilities: () -> Hash[Symbol, untyped]
+      def analyze: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+      def diff2: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+      def merge2: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+      def merge3: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+    end
+
+    class Provider < SourcePreservingProvider
+    end
+
+    def self.merge_provider: () -> Provider
+    def self.register_provider!: (?replace: bool) -> untyped
+
     module Version
       VERSION: String
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yaml-merge
 version: !ruby/object:Gem::Version
-  version: 7.1.6
+  version: 7.1.8
 platform: ruby
 authors:
 - Peter H. Boling
@@ -43,28 +43,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.6
+        version: 7.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.6
+        version: 7.1.8
 - !ruby/object:Gem::Dependency
   name: tree_haver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.6
+        version: 7.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.6
+        version: 7.1.8
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -94,7 +94,7 @@ dependencies:
         version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.17
+        version: 3.0.31
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -104,7 +104,7 @@ dependencies:
         version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.17
+        version: 3.0.31
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -182,7 +182,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.2
+        version: 3.2.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -192,7 +192,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.2
+        version: 3.2.3
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -222,7 +222,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.6
+        version: 3.2.7
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -232,7 +232,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.6
+        version: 3.2.7
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -304,7 +304,9 @@ files:
 - lib/yaml/merge/file_analysis.rb
 - lib/yaml/merge/merge_result.rb
 - lib/yaml/merge/node_wrapper.rb
+- lib/yaml/merge/provider.rb
 - lib/yaml/merge/smart_merger.rb
+- lib/yaml/merge/source_preserving_provider.rb
 - lib/yaml/merge/version.rb
 - sig/yaml/merge.rbs
 homepage: https://github.com/structuredmerge/structuredmerge-ruby
@@ -313,10 +315,10 @@ licenses:
 - PolyForm-Small-Business-1.0.0
 metadata:
   homepage_uri: https://structuredmerge.org
-  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.6
-  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.6/CHANGELOG.md
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.8
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.8/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/yaml-merge/7.1.6
+  documentation_uri: https://www.rubydoc.info/gems/yaml-merge/7.1.8
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/yaml-merge