toml-merge 7.1.1 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c72304ec6fb3ac2231f4d7997634eee95539439a658b652ea7ae7333491a8929
-  data.tar.gz: 31f483b3bb9440c62dfc47fc3ea97c26e2c26123e322f8ae6c6052bdf2b5ff50
+  metadata.gz: 1897d1ad4cb680eef623f8a329d9c0c917345e30f9997e340e91ae35e9f57d01
+  data.tar.gz: e858428956c256aef47413f8efe5d9aa01b246ef160527b14d02857e4b3ac18f
 SHA512:
-  metadata.gz: 67eb8d1b954629819cde2b3bb8cfd5067cd2b039feaf19ede96322af45a0dc50cd5f14874108015de67aa3bbeaf58292fe92955d0d6102cb4e337051dbb9fbb4
-  data.tar.gz: b96748e39aa82cc42d8e60c76d741d0c25840ad9e7b4d23e1e090b8e4ac7761628f0740f276fb2b52d265c664e82989b71e5bfd134e936b0d3e586d842378954
+  metadata.gz: 19015402b3398c6d2ea9babedd05a76b2b7d681f946f83eae5fc32b5097f2f3fa3bd97c0e0736c9c4c0753b4ced6a8de670c96d77ce0f8d8bba8d224bbb0916d
+  data.tar.gz: 142922345fc8ba7158cc809f082453789b8b5fa3553628f06703b6d49b46834c0d48c61abb006cc33d08266edc4f671c36aa9870da4dbb70667abfaa7933f043

data/README.md

@@ -90,7 +90,7 @@ puts result.content if result.success?
 
 ### Compatibility
 
-Compatible with MRI Ruby 4.0.0+, and concordant releases of JRuby, and TruffleRuby.
+Compatible with MRI Ruby 4.0.0+, JRuby, and TruffleRuby.
 CI workflows and Appraisals are generated for MRI Ruby 4.0.0+.
 This test floor is configured by `ruby.test_minimum` in `.kettle-jem.yml` and
 may be higher than the gem's runtime compatibility floor when legacy Rubies are
@@ -178,20 +178,12 @@ See [SECURITY.md][🔐security].
 ## 🤝 Contributing
 
 If you need some ideas of where to help, you could work on adding more code coverage,
-or if it is already 💯 (see [below](#code-coverage)) check [issues][🤝gh-issues] or [PRs][🤝gh-pulls],
-or use the gem and think about how it could be better.
+check [issues][🤝gh-issues] or [PRs][🤝gh-pulls], or use the gem and think about how it could be better.
 
 We [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] so if you make changes, remember to update it.
 
 See [CONTRIBUTING.md][🤝contributing] for more detailed instructions.
 
-### Code Coverage
-
-<details markdown="1">
-<summary>Coverage service badges</summary>
-
-</details>
-
 ## 📌 Versioning
 
 This library follows [![Semantic Versioning 2.0.0][📌semver-img]][📌semver] for its public API where practical.

data/lib/toml/merge/provider.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Toml
+  # Portable TOML workflow integration.
+  module Merge
+    # Source-preserving TOML workflow configured for kreuzberg-language-pack.
+    class Provider < SourcePreservingProvider
+      PROVIDER_ID = 'ruby.toml'
+      BACKEND = TREE_SITTER_BACKEND_REFERENCE
+      PACKAGE_NAME = Merge::PACKAGE_NAME
+      PACKAGE_VERSION = Version::VERSION
+      ROLE = :workflow
+    end
+
+    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/toml/merge/source_preserving_provider.rb

@@ -0,0 +1,871 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Toml
+  module Merge
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- provider validation, planning, rendering, and verification form one safety boundary
+    # Backend-parameterized conservative source-preserving provider for top-level TOML mappings.
+    class SourcePreservingProvider
+      DEFAULT_PROFILE = :source_preserving
+      DIALECTS = %i[toml].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 = 'toml'
+      def backend_reference = self.class::BACKEND
+      def backend_id = backend_reference.id
+      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.to_sym],
+          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),
+          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?
+
+        additions = documents[:incoming].entries.reject { |entry| documents[:current].by_key.key?(entry.key) }
+        render_documents = { ours: documents[:current], theirs: documents[:incoming] }
+        fragments = [whole_source_fragment(:ours, documents[:current].source)]
+        fragments.concat(additions.map { |entry| entry_fragment(:theirs, entry) })
+        rendered = render_plan(request, separated_fragments(fragments, render_documents))
+        expected = [
+          *documents[:current].entries.map { |entry| selected_entry(entry, :current) },
+          *additions.map { |entry| selected_entry(entry, :incoming) }
+        ]
+        verification = verify_composite(rendered.content, expected)
+        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, :exact_mapping_entry_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)
+        analysis = TreeHaver.with_backend(backend_id) { ::Toml::Merge::FileAnalysis.new(source) }
+        unless analysis.valid?
+          message = analysis.errors.map(&:to_s).join('; ')
+          return invalid_document(role, source, :parse_error, message.empty? ? 'TOML parse failed' : message)
+        end
+
+        issues = []
+        if (table = analysis.tables.find(&:table?))
+          issues << issue(
+            :table,
+            'TOML tables require an exact one-sided merge',
+            source_lines: [table.start_line, table.effective_end_line]
+          )
+        end
+        if (table_array = analysis.tables.find(&:array_of_tables?))
+          issues << issue(
+            :array_of_tables,
+            'TOML arrays of tables require an exact one-sided merge',
+            source_lines: [table_array.start_line, table_array.effective_end_line]
+          )
+        end
+        entries = mapping_entries(analysis, source, role)
+        duplicate = entries.group_by(&:key).find { |_key, matches| matches.length > 1 }
+        if duplicate
+          issues << issue(
+            :duplicate_key,
+            "Duplicate TOML key #{duplicate.first}",
+            key: duplicate.first,
+            source_lines: duplicate.last.map { |entry| [entry.start_line, entry.end_line] }
+          )
+        end
+        entries.each do |entry|
+          if entry.key.include?('.')
+            issues << issue(
+              :dotted_key,
+              "TOML key #{entry.key} has ambiguous ownership",
+              key: entry.key,
+              source_lines: [entry.start_line, entry.end_line]
+            )
+          end
+          next if entry.ownership_provable
+
+          issues << issue(
+            :unprovable_range,
+            "TOML key #{entry.key} has no provable source range",
+            key: entry.key,
+            source_lines: [entry.start_line, entry.end_line]
+          )
+        end
+
+        Document.new(
+          role: role,
+          source: source,
+          analysis: analysis,
+          entries: entries.freeze,
+          by_key: entries.to_h { |entry| [entry.key, entry] }.freeze,
+          issues: issues.freeze,
+          document_attributes: node_attributes(analysis.root_node)
+        )
+      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_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 mapping_entries(analysis, source, role)
+        analysis.root_pairs.filter_map.with_index do |pair, index|
+          build_entry(analysis, pair, source, role, index)
+        end
+      end
+
+      def build_entry(analysis, pair, source, role, index)
+        key = pair.key_name
+        value = pair.value_node
+        key_line = pair.start_line
+        value_end = pair.end_line
+        return unless key && value && key_line && value_end && value_end >= key_line
+
+        leading_start = owned_leading_start(analysis, pair, index, key_line)
+        fragment = source_lines(source, leading_start, value_end)
+        Entry.new(
+          key: key,
+          start_line: leading_start,
+          end_line: value_end,
+          fragment: fragment,
+          semantic: node_semantic(value),
+          attributes: node_attributes(value),
+          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_semantic(node)
+        {
+          type: node.canonical_type.to_s,
+          source_value: node.text
+        }.freeze
+      end
+
+      def node_attributes(node)
+        return {} unless node
+
+        {
+          type: node.type.to_s,
+          canonical_type: node.canonical_type.to_s,
+          signature: public_value(node.signature)
+        }.freeze
+      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
+
+      def analysis_payload(document)
+        {
+          dialect: 'toml',
+          backend: backend_id,
+          document_attributes: document.document_attributes,
+          entries: document.entries.map do |entry|
+            {
+              key: entry.key,
+              value: entry.semantic,
+              attributes: entry.attributes,
+              source_role: document.role,
+              source_lines: [entry.start_line, entry.end_line]
+            }
+          end,
+          structurally_unambiguous: document.issues.empty?
+        }
+      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,
+          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 entry_state(left) == entry_state(right)
+
+          { path: "/#{key}", ours: :unchanged, theirs: change_kind(left, right) }.freeze
+        end.freeze
+      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| localized_conflict_position(conflict, documents) }
+          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] }
+        inserted_conflicts = conflicts.select { |conflict| conflict.ours.nil? }
+        insert_before = inserted_conflicts.group_by do |conflict|
+          localized_conflict_position(conflict, documents)
+        end
+        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
+          Array(insert_before[entry.key]).each { |conflict| fragments << conflict_fragment(request, conflict) }
+          conflict = by_key[entry.key]
+          fragments << (conflict ? conflict_fragment(request, conflict) : entry_fragment(:ours, entry))
+          cursor = entry.end_line + 1
+        end
+        Array(insert_before[:append]).each { |conflict| fragments << conflict_fragment(request, conflict) }
+        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 localized_conflict_position(conflict, documents)
+        return conflict.key if conflict.ours&.ownership_provable
+        return unless conflict.base&.ownership_provable && conflict.theirs&.ownership_provable
+
+        base_keys = documents[:base].entries.map(&:key)
+        conflict_index = base_keys.index(conflict.key)
+        return unless conflict_index
+
+        following_anchor = base_keys.drop(conflict_index + 1).find { |key| documents[:ours].by_key.key?(key) }
+        following_anchor || :append
+      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)
+        "toml-mapping-#{Digest::SHA256.hexdigest(key)[0, 16]}"
+      end
+
+      def conflict_failure(request, decisions, conflicts, rendered, strategy)
+        failure(
+          :merge3,
+          request,
+          category: :merge_conflict,
+          message: 'TOML 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} TOML 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 TOML layout or comments changed independently.',
+            blocking: true
+          }]
+        )
+      end
+
+      def full_file_conflict(request, documents, decisions, conflicts, reason, diagnostics: nil)
+        conflict = { conflict_id: 'toml-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: 'TOML 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, toml_key: entry.key)
+        end
+
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: "#{entry.fragment}\n",
+          reason: :conflict_line_boundary,
+          producer: provider_id,
+          metadata: { source_role: role, toml_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} TOML 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 TOML 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] || :toml,
+            backend: request[:backend] || backend_id.to_sym,
+            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/toml/merge/version.rb

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

data/lib/toml/merge.rb

@@ -108,6 +108,7 @@ module Toml
     autoload :NodeWrapper, 'toml/merge/node_wrapper'
     autoload :ConflictResolver, 'toml/merge/conflict_resolver'
     autoload :SmartMerger, 'toml/merge/smart_merger'
+    autoload :SourcePreservingProvider, 'toml/merge/source_preserving_provider'
     autoload :TableMatchRefiner, 'toml/merge/table_match_refiner'
 
     class << self
@@ -365,6 +366,8 @@ module Toml
 end
 
 Toml::Merge.register_backend!
+require_relative 'merge/provider'
+Toml::Merge.register_provider!
 
 # Register with ast-merge's MergeGemRegistry for RSpec dependency tags
 # Only register if MergeGemRegistry is loaded (i.e., in test environment)

data/sig/toml/merge.rbs

@@ -1,5 +1,26 @@
 module Toml
   module Merge
+    class SourcePreservingProvider
+      def provider_id: () -> String
+      def family: () -> String
+      def backend_reference: () -> untyped
+      def backend_id: () -> String
+      def package_name: () -> String
+      def package_version: () -> String
+      def role: () -> Symbol
+      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: toml-merge
 version: !ruby/object:Gem::Version
-  version: 7.1.1
+  version: 7.1.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -43,28 +43,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
 - !ruby/object:Gem::Dependency
   name: tree_haver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -91,20 +91,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.5.17
+        version: 3.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.5.17
+        version: 3.0.0
 - !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.0
+        version: 3.2.2
   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.0
+        version: 3.2.2
 - !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.4
+        version: 3.2.5
   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.4
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -308,7 +308,9 @@ files:
 - lib/toml/merge/merge_result.rb
 - lib/toml/merge/node_type_normalizer.rb
 - lib/toml/merge/node_wrapper.rb
+- lib/toml/merge/provider.rb
 - lib/toml/merge/smart_merger.rb
+- lib/toml/merge/source_preserving_provider.rb
 - lib/toml/merge/table_match_refiner.rb
 - lib/toml/merge/version.rb
 - sig/toml/merge.rbs
@@ -318,10 +320,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.1
-  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.1/CHANGELOG.md
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.3
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/toml-merge/7.1.1
+  documentation_uri: https://www.rubydoc.info/gems/toml-merge/7.1.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/toml-merge