prism-merge 7.1.1 → 7.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e746e33165b81c8213b46fb68de60386a0bb0bd88ad29e4abeb4bc0e9d9a7050
-  data.tar.gz: fec3c1ad285a6cea78b69c68d499fdca8856113abb3c2c79e22a72c565773042
+  metadata.gz: 7d32fbdcd833e576a54414849501db40ddacd349498c05e4d233159f2e5521c1
+  data.tar.gz: 063f4adb55b355f984f09eb376652dded9e8a8d2451d993ebc4a954eb403ca0c
 SHA512:
-  metadata.gz: 94060d0dd8879f84e4516e118b606454f14df7203cacad358392d1f8e666b0282757ee9044bdc047ad8f2c612437d8066d16be7d0a0803ce5d4eb31415c242f2
-  data.tar.gz: 34d11e92d49b0fa616604f8c6396100d21d7ca3d7d69549978835bec42145c211e9aa085b2fae58a2322990ac910dff0c68591b97096cda7854db98409d9814a
+  metadata.gz: 291ed360148759fb7f32d3c28da2d0c8da02733022b60b9ada62781cd0cfc61d0295164e43f84985816d2416f92f433862e04010ec2ac59c200f953918e8c540
+  data.tar.gz: 75c2f6a59e5910332a80945f0f12426d5a019872d4e128834cebabfc496db6c30d2ab389940a7bc10910a084694bf68d59e9bcd81281dbbc173857d86b6a59a5

data/README.md

@@ -83,7 +83,7 @@ File.write("merged.rb", result)
 
 ### 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
@@ -1099,20 +1099,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.
@@ -1252,7 +1244,7 @@ If none of the available licenses suit your use case, please [contact us](mailto
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.246-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.550-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/structuredmerge/structuredmerge-ruby/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/prism/merge/provider.rb

@@ -0,0 +1,717 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Prism
+  module Merge
+    # Base-aware, source-preserving Ruby provider backed by Prism top-level owners.
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- provider decisions, source plans, and verification form one boundary
+    class Provider
+      DEFAULT_PROFILE = :source_preserving
+      Owner = Data.define(:id, :signature, :fingerprint, :start_line, :end_line, :role)
+      Document = Data.define(:source, :analysis, :owners, :by_id, :unmanaged_fingerprint)
+      Decision = Data.define(:changes, :conflicts, :choices)
+
+      def provider_id = 'ruby.ruby.prism'
+      def family = 'ruby'
+
+      def capabilities
+        {
+          operations: Ast::Merge::ProviderContract::OPERATIONS,
+          dialects: %i[ruby],
+          backends: %i[prism],
+          profiles: [DEFAULT_PROFILE],
+          role: :backend,
+          source_preservation: %i[exact_source owner_fragments line_provenance reparse semantic_verification]
+        }.freeze
+      end
+
+      def analyze(request)
+        document = parse_document(:analyze, request, :source)
+        return document if provider_failure?(document)
+
+        result(
+          :analyze,
+          request,
+          analysis: {
+            backend: 'prism',
+            valid: true,
+            owners: document.owners.map { |owner| owner_description(owner) }
+          },
+          verification: { source_parsed: true }
+        )
+      end
+
+      def diff2(request)
+        before = parse_document(:diff2, request, :before)
+        return before if provider_failure?(before)
+
+        after = parse_document(:diff2, request, :after)
+        return after if provider_failure?(after)
+
+        changes = diff_documents(before, after)
+        result(
+          :diff2,
+          request,
+          diff: { changes: changes },
+          changes: changes,
+          verification: { before_parsed: true, after_parsed: true }
+        )
+      end
+
+      def merge2(request)
+        merged = Prism::Merge.merge_ruby(
+          request.fetch(:incoming_source),
+          request.fetch(:current_source),
+          'ruby',
+          backend: request[:backend],
+          add_template_only_nodes: true
+        )
+        return merge2_failure(request, merged) unless merged[:ok]
+
+        output = merged.fetch(:output)
+        parsed = parse_source(output, :output)
+        return render_failure(:merge2, request, parsed) if provider_failure?(parsed)
+
+        result(
+          :merge2,
+          request,
+          output: output,
+          render_report: { strategy: :prism_smart_merger, synthesis: :family_emission },
+          verification: { output_reparsed: true }
+        )
+      end
+
+      def merge3(request)
+        documents = parse_merge3_documents(request)
+        return documents if provider_failure?(documents)
+
+        exact_role = exact_revision_role(request)
+        decision = decide(documents, include_unmanaged_conflict: exact_role.nil?)
+        return render_conflicts(request, documents, decision) unless decision.conflicts.empty?
+
+        return render_exact(request, documents, decision, exact_role) if exact_role
+
+        render_composite(request, documents, decision)
+      end
+
+      private
+
+      def parse_merge3_documents(request)
+        %i[base ours theirs].each_with_object({}) do |role, documents|
+          document = parse_document(:merge3, request, role)
+          return document if provider_failure?(document)
+
+          documents[role] = document
+        end
+      end
+
+      def parse_document(operation, request, role)
+        source = request.fetch(role == :source ? :source : :"#{role}_source")
+        parsed = parse_source(source, role)
+        return parse_failure(operation, request, role, parsed) if provider_failure?(parsed)
+
+        parsed
+      end
+
+      def parse_source(source, role)
+        analysis = Prism::Merge::FileAnalysis.new(source, source_label: role.to_s)
+        unless analysis.valid?
+          return {
+            parse_error: analysis.errors.map(&:message).join('; '),
+            source_role: role
+          }
+        end
+
+        owners = analysis.nodes_with_comments.map do |node_info|
+          signature = node_info.fetch(:signature)
+          Owner.new(
+            id: owner_id(signature),
+            signature: signature,
+            fingerprint: owner_fingerprint(source, node_info),
+            start_line: node_info.fetch(:line_range).begin,
+            end_line: node_info.fetch(:line_range).end,
+            role: role
+          )
+        end
+        duplicate = owners.group_by(&:id).find { |_id, matches| matches.length > 1 }
+        return { ambiguous_owner: duplicate.first, source_role: role } if duplicate
+
+        Document.new(
+          source: source,
+          analysis: analysis,
+          owners: owners.freeze,
+          by_id: owners.to_h { |owner| [owner.id, owner] }.freeze,
+          unmanaged_fingerprint: unmanaged_fingerprint(source, owners)
+        )
+      end
+
+      def unmanaged_fingerprint(source, owners)
+        owned_lines = owners.each_with_object({}) do |owner, lines|
+          (owner.start_line..owner.end_line).each { |line| lines[line] = true }
+        end
+        source.lines.each_with_index.filter_map do |line, index|
+          line unless owned_lines[index + 1]
+        end.join
+      end
+
+      def semantic_fingerprint(value)
+        case value
+        when ::Prism::Node
+          fields = value.deconstruct_keys(nil).reject do |key, _item|
+            key == :node_id || key == :location || key.to_s.end_with?('_loc')
+          end
+          [value.type, fields.map { |key, item| [key, semantic_fingerprint(item)] }]
+        when Array
+          value.map { |item| semantic_fingerprint(item) }
+        when Hash
+          value.map { |key, item| [key, semantic_fingerprint(item)] }
+        else
+          value
+        end
+      end
+
+      def owner_fingerprint(source, node_info)
+        range = node_info.fetch(:line_range)
+        {
+          ast: semantic_fingerprint(node_info.fetch(:node)),
+          source: source.lines.slice(range.begin - 1, range.end - range.begin + 1).join.delete_suffix("\n"),
+          leading_comments: node_info.fetch(:leading_comments).map(&:slice),
+          inline_comments: node_info.fetch(:inline_comments).map(&:slice)
+        }.freeze
+      end
+
+      def owner_id(signature)
+        Digest::SHA256.hexdigest(Marshal.dump(signature))
+      end
+
+      def owner_path(owner)
+        owner ? owner.signature.inspect : '<document>'
+      end
+
+      def owner_description(owner)
+        {
+          path: owner_path(owner),
+          signature: owner.signature,
+          line_range: [owner.start_line, owner.end_line]
+        }
+      end
+
+      def diff_documents(before, after)
+        ordered_ids(before, after).filter_map do |id|
+          left = before.by_id[id]
+          right = after.by_id[id]
+          next if left && right && left.fingerprint == right.fingerprint
+
+          {
+            path: owner_path(left || right),
+            ours: :unchanged,
+            theirs: change_kind(left, right)
+          }.freeze
+        end.freeze
+      end
+
+      def ordered_ids(*documents)
+        documents.flat_map { |document| document.owners.map(&:id) }.uniq
+      end
+
+      def change_kind(before, after)
+        return :added unless before
+        return :deleted unless after
+
+        :edited
+      end
+
+      def decide(documents, include_unmanaged_conflict:)
+        changes = []
+        conflicts = []
+        choices = {}
+        append_unmanaged_conflict(changes, conflicts, documents) if include_unmanaged_conflict
+        ordered_ids(*documents.values).each do |id|
+          base = documents.fetch(:base).by_id[id]
+          ours = documents.fetch(:ours).by_id[id]
+          theirs = documents.fetch(:theirs).by_id[id]
+          ours_change = side_change(base, ours)
+          theirs_change = side_change(base, theirs)
+          next choices[id] = :ours if ours_change == :unchanged && theirs_change == :unchanged
+
+          change = {
+            path: owner_path(base || ours || theirs),
+            ours: ours_change,
+            theirs: theirs_change
+          }.freeze
+          changes << change
+          choice = owner_choice(base, ours, theirs)
+          if choice == :conflict
+            conflicts << conflict_for(id, base, ours, theirs, change)
+          else
+            choices[id] = choice
+          end
+        end
+        Decision.new(changes: changes.freeze, conflicts: conflicts.freeze, choices: choices.freeze)
+      end
+
+      def append_unmanaged_conflict(changes, conflicts, documents)
+        base = documents.fetch(:base).unmanaged_fingerprint
+        ours = documents.fetch(:ours).unmanaged_fingerprint
+        theirs = documents.fetch(:theirs).unmanaged_fingerprint
+        return if ours == theirs || base == theirs
+
+        change = {
+          path: '<unmanaged-source>',
+          ours: base == ours ? :unchanged : :edited,
+          theirs: base == theirs ? :unchanged : :edited
+        }.freeze
+        changes << change
+        conflicts << {
+          conflict_id: "ruby-unmanaged-#{Digest::SHA256.hexdigest([base, ours, theirs].join("\0"))[0, 16]}",
+          category: :unmanaged_source_change,
+          path: change.fetch(:path),
+          owner_id: nil,
+          change_classification: change
+        }.freeze
+      end
+
+      def side_change(base, side)
+        return :unchanged if base && side && base.fingerprint == side.fingerprint
+        return :added if !base && side
+        return :deleted if base && !side
+        return :unchanged unless base || side
+
+        :edited
+      end
+
+      def owner_choice(base, ours, theirs)
+        return :ours if equivalent?(ours, theirs)
+        return :theirs if equivalent?(base, ours)
+        return :ours if equivalent?(base, theirs)
+        return nil if ours.nil? && theirs.nil?
+
+        :conflict
+      end
+
+      def equivalent?(left, right)
+        return true if left.nil? && right.nil?
+        return false unless left && right
+
+        left.fingerprint == right.fingerprint
+      end
+
+      def conflict_for(id, base, ours, theirs, change)
+        {
+          conflict_id: "ruby-owner-#{id[0, 16]}",
+          category: base && (!ours || !theirs) ? :delete_edit : :edit_edit,
+          path: change.fetch(:path),
+          owner_id: id,
+          base: owner_state(base),
+          ours: owner_state(ours),
+          theirs: owner_state(theirs),
+          change_classification: change
+        }.freeze
+      end
+
+      def owner_state(owner)
+        { present: !owner.nil?, fingerprint: owner&.fingerprint }.freeze
+      end
+
+      def exact_revision_role(request)
+        base = request.fetch(:base_source)
+        ours = request.fetch(:ours_source)
+        theirs = request.fetch(:theirs_source)
+        return :ours if ours == theirs || base == theirs
+
+        :theirs if base == ours
+      end
+
+      def render_exact(request, documents, decision, role)
+        rendered = render_plan(request, [whole_source_fragment(role, request.fetch(:"#{role}_source"))])
+        verification = verify_rendered(rendered.content, documents.fetch(role).owners, role: :output)
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: decision.changes,
+          render_report: render_report(rendered, :exact_revision),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def render_composite(request, documents, decision)
+        fragments = composite_fragments(documents, decision)
+        rendered = render_plan(request, fragments)
+        expected = expected_owners(documents, decision)
+        verification = verify_rendered(rendered.content, expected, role: :output)
+        unless verification[:semantic_match]
+          return failure(
+            :merge3,
+            request,
+            category: :render_failure,
+            message: 'Prism composite did not match the planned top-level owner structure.',
+            changes: decision.changes,
+            render_report: render_report(rendered, :exact_owner_composite),
+            verification: verification.merge(base_participated: true)
+          )
+        end
+
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: decision.changes,
+          render_report: render_report(rendered, :exact_owner_composite),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def composite_fragments(documents, decision)
+        ours = documents.fetch(:ours)
+        edits = replacement_edits(documents, decision)
+        fragments = []
+        cursor = 1
+        edits.sort_by { |edit| edit.fetch(:start_line) }.each do |edit|
+          append_range(fragments, :ours, cursor, edit.fetch(:start_line) - 1)
+          replacement = edit[:owner]
+          append_owner(fragments, replacement) if replacement
+          cursor = edit.fetch(:end_line) + 1
+        end
+        append_range(fragments, :ours, cursor, ours.source.lines.length)
+        append_additions(fragments, documents, decision)
+        fragments
+      end
+
+      def replacement_edits(documents, decision)
+        ours = documents.fetch(:ours)
+        decision.choices.filter_map do |id, role|
+          ours_owner = ours.by_id[id]
+          next unless ours_owner
+
+          chosen = role && documents.fetch(role).by_id[id]
+          next if role == :ours
+
+          { start_line: ours_owner.start_line, end_line: ours_owner.end_line, owner: chosen }
+        end
+      end
+
+      def append_additions(fragments, documents, decision)
+        ours = documents.fetch(:ours)
+        additions = documents.fetch(:theirs).owners.select do |owner|
+          !ours.by_id.key?(owner.id) && decision.choices[owner.id] == :theirs
+        end
+        return if additions.empty?
+
+        ensure_plan_boundary!(fragments, documents)
+        additions.each_with_index do |owner, index|
+          append_owner(fragments, owner)
+          ensure_plan_boundary!(fragments, documents) if index < additions.length - 1
+        end
+      end
+
+      def ensure_plan_boundary!(fragments, documents)
+        fragment = fragments.last
+        return if fragment.nil? || fragment_content(fragment, documents).end_with?("\n")
+
+        if fragment.is_a?(Ast::Merge::SourceRender::SourceFragment) && fragment.start_line < fragment.end_line
+          fragments[-1] = source_range_fragment(fragment.revision, fragment.start_line, fragment.end_line - 1)
+        else
+          fragments.pop
+        end
+        content = if fragment.is_a?(Ast::Merge::SourceRender::SourceFragment)
+                    documents.fetch(fragment.revision).source.lines.fetch(fragment.end_line - 1)
+                  else
+                    fragment.content
+                  end
+        fragments << Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: "#{content}\n",
+          reason: :owner_separator,
+          producer: provider_id,
+          metadata: { copied_source: true }
+        )
+      end
+
+      def fragment_content(fragment, documents)
+        return fragment.content if fragment.is_a?(Ast::Merge::SourceRender::SynthesizedFragment)
+
+        document = documents.fetch(fragment.revision)
+        document.source.lines.slice(fragment.start_line - 1, fragment.end_line - fragment.start_line + 1).join
+      end
+
+      def append_owner(fragments, owner)
+        fragments << source_range_fragment(owner.role, owner.start_line, owner.end_line)
+      end
+
+      def append_range(fragments, role, start_line, end_line)
+        return if start_line > end_line
+
+        fragments << source_range_fragment(role, start_line, end_line)
+      end
+
+      def expected_owners(documents, decision)
+        ours = documents.fetch(:ours)
+        expected = ours.owners.filter_map do |owner|
+          role = decision.choices[owner.id]
+          role && documents.fetch(role).by_id[owner.id]
+        end
+        documents.fetch(:theirs).owners.each do |owner|
+          next if ours.by_id.key?(owner.id)
+          next unless decision.choices[owner.id] == :theirs
+
+          expected << owner
+        end
+        expected
+      end
+
+      def verify_rendered(output, expected, role:)
+        parsed = parse_source(output, role)
+        if provider_failure?(parsed)
+          return {
+            output_reparsed: false,
+            semantic_match: false,
+            parse_error: parsed[:parse_error]
+          }
+        end
+
+        actual = parsed.owners.map { |owner| [owner.id, owner.fingerprint] }
+        planned = expected.map { |owner| [owner.id, owner.fingerprint] }
+        {
+          output_reparsed: true,
+          semantic_match: actual == planned,
+          planned_owner_count: planned.length,
+          output_owner_count: actual.length
+        }
+      end
+
+      def render_conflicts(request, documents, decision)
+        localized = localized_conflict_fragments(request, documents, decision)
+        if localized
+          rendered = render_plan(request, localized)
+          return conflict_failure(request, decision, rendered, :owner_localized_conflict)
+        end
+
+        rendered = render_plan(request, [whole_document_conflict(request, decision)])
+        conflict_failure(
+          request,
+          decision,
+          rendered,
+          :full_file_conflict,
+          fallbacks: [{ from: :owner_localization, to: :full_file_conflict, reason: :owner_not_addressable }]
+        )
+      end
+
+      def localized_conflict_fragments(request, documents, decision)
+        ours = documents.fetch(:ours)
+        return unless decision.conflicts.all? do |conflict|
+          ours.by_id.key?(conflict.fetch(:owner_id))
+        end
+
+        ranges = decision.conflicts.map do |conflict|
+          [conflict, ours.by_id.fetch(conflict.fetch(:owner_id))]
+        end
+        return unless ranges.sort_by { |_conflict, owner| owner.start_line }.each_cons(2).none? do |left, right|
+          left.last.end_line >= right.last.start_line
+        end
+
+        fragments = []
+        cursor = 1
+        ranges.sort_by { |_conflict, owner| owner.start_line }.each do |conflict, owner|
+          append_range(fragments, :ours, cursor, owner.start_line - 1)
+          fragments << owner_conflict_fragment(request, documents, conflict)
+          cursor = owner.end_line + 1
+        end
+        append_range(fragments, :ours, cursor, ours.source.lines.length)
+        fragments
+      end
+
+      def owner_conflict_fragment(request, documents, conflict)
+        Ast::Merge::SourceRender::ConflictFragment.new(
+          conflict_id: conflict.fetch(:conflict_id),
+          base: conflict_owner_side(documents, conflict, :base),
+          ours: conflict_owner_side(documents, conflict, :ours),
+          theirs: conflict_owner_side(documents, conflict, :theirs),
+          labels: request.fetch(:labels, {}),
+          marker_size: request.fetch(:conflict_marker_size, 7),
+          metadata: { path: conflict.fetch(:path), category: conflict.fetch(:category) }
+        )
+      end
+
+      def conflict_owner_side(documents, conflict, role)
+        document = documents.fetch(role)
+        owner = document.by_id[conflict.fetch(:owner_id)]
+        owner ? [conflict_source_fragment(owner, document.source)] : []
+      end
+
+      def whole_document_conflict(request, decision)
+        Ast::Merge::SourceRender::ConflictFragment.new(
+          conflict_id: decision.conflicts.first.fetch(:conflict_id),
+          base: [conflict_whole_source_fragment(:base, request.fetch(:base_source))],
+          ours: [conflict_whole_source_fragment(:ours, request.fetch(:ours_source))],
+          theirs: [conflict_whole_source_fragment(:theirs, request.fetch(:theirs_source))],
+          labels: request.fetch(:labels, {}),
+          marker_size: request.fetch(:conflict_marker_size, 7),
+          metadata: { conflicts: decision.conflicts.map { |conflict| conflict[:conflict_id] } }
+        )
+      end
+
+      def conflict_source_fragment(owner, source)
+        fragment_source = source.lines.slice(owner.start_line - 1, owner.end_line - owner.start_line + 1).join
+        return source_range_fragment(owner.role, owner.start_line, owner.end_line) if fragment_source.end_with?("\n")
+
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: "#{fragment_source}\n",
+          reason: :conflict_line_boundary,
+          producer: provider_id,
+          metadata: { source_role: owner.role, copied_source: true }
+        )
+      end
+
+      def conflict_whole_source_fragment(role, source)
+        return whole_source_fragment(role, source) if source.empty? || 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 whole_source_fragment(role, source)
+        return empty_source_fragment(role) if source.empty?
+
+        source_range_fragment(role, 1, source.lines.length)
+      end
+
+      def empty_source_fragment(role)
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: '',
+          reason: :exact_empty_source,
+          producer: provider_id,
+          metadata: { source_role: role }
+        )
+      end
+
+      def source_range_fragment(role, start_line, end_line)
+        Ast::Merge::SourceRender::SourceFragment.new(
+          revision: role,
+          start_line: start_line,
+          end_line: end_line,
+          metadata: { source_role: role }
+        )
+      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].to_s,
+              theirs: request[:theirs_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 conflict_failure(request, decision, rendered, strategy, fallbacks: [])
+        failure(
+          :merge3,
+          request,
+          category: :merge_conflict,
+          message: 'Ruby top-level owner changed incompatibly on both sides.',
+          changes: decision.changes,
+          conflicts: decision.conflicts,
+          conflicted_output: rendered.content,
+          render_report: render_report(rendered, strategy),
+          verification: { base_participated: true },
+          fallbacks: fallbacks
+        )
+      end
+
+      def merge2_failure(request, merged)
+        failure(
+          :merge2,
+          request,
+          category: :merge_failure,
+          message: Array(merged[:diagnostics]).map { |item| item[:message] }.compact.join('; ')
+        )
+      end
+
+      def parse_failure(operation, request, role, parsed)
+        detail = parsed[:parse_error] || "ambiguous duplicate owner #{parsed[:ambiguous_owner].inspect}"
+        failure(
+          operation,
+          request,
+          category: parsed[:parse_error] ? :parse_error : :ambiguous_owner,
+          message: "#{role} parse error: #{detail}",
+          source_role: role
+        )
+      end
+
+      def render_failure(operation, request, parsed)
+        failure(
+          operation,
+          request,
+          category: :render_failure,
+          message: "Prism emitter produced invalid output: #{parsed[:parse_error]}",
+          source_role: :output
+        )
+      end
+
+      def provider_failure?(value)
+        value.is_a?(Hash) && (value[:ok] == false || value.key?(:parse_error) || value.key?(:ambiguous_owner))
+      end
+
+      def result(operation, request, changes: [], render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: true,
+          envelope: envelope(request, changes: changes, render_report: render_report, verification: verification),
+          **payload
+        )
+      end
+
+      def failure(operation, request, category:, message:, changes: [], conflicts: [], fallbacks: [],
+                  render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: false,
+          envelope: envelope(
+            request,
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            diagnostics: [{ category: category, severity: :error, message: message, blocking: true }],
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def envelope(request, **fields)
+        {
+          provider: {
+            provider_id: provider_id,
+            family: family,
+            dialect: request[:dialect] || :ruby,
+            backend: request[:backend] || :prism,
+            package: Prism::Merge::PACKAGE_NAME,
+            package_version: Prism::Merge::Version::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/prism/merge/version.rb

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

data/lib/prism/merge.rb

@@ -7,6 +7,9 @@ require 'tree_haver'
 require_relative 'merge/version'
 
 module Prism
+  # This public facade keeps provider protocol and backend registration
+  # entrypoints together; implementation details live in autoloaded files.
+  # rubocop:disable Metrics/ModuleLength
   module Merge
     module_function
 
@@ -62,6 +65,7 @@ module Prism
     autoload :NodeWrapper, 'prism/merge/node_wrapper'
     autoload :PartialTemplateMerger, 'prism/merge/partial_template_merger'
     autoload :PartialTemplateNode, 'prism/merge/partial_template_node'
+    autoload :Provider, 'prism/merge/provider'
     autoload :RecursiveMergePolicy, 'prism/merge/recursive_merge_policy'
     autoload :RecursiveNodeBodyMerger, 'prism/merge/recursive_node_body_merger'
     autoload :RubyDocSurfaceAnalyzer, 'prism/merge/ruby_doc_surface_analyzer'
@@ -90,6 +94,14 @@ module Prism
       Ruby::Merge.ruby_feature_profile
     end
 
+    def merge_provider
+      @merge_provider ||= Provider.new
+    end
+
+    def register_provider!(replace: false)
+      Ast::Merge.register_provider(merge_provider, replace: replace)
+    end
+
     def available_ruby_backends
       [BACKEND_REFERENCE]
     end
@@ -300,6 +312,8 @@ module Prism
       }
     end
 
+    # This projection mirrors the nested public schema intentionally.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def ruby_structured_edit_batch_report_projection
       content = "class App\n  # managed snippet\n  old_call\n\n  anchor_call\n\n  # obsolete snippet\n  obsolete_call\nend\n"
       {
@@ -441,7 +455,10 @@ module Prism
         )
       }
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
+    # Keep parser validation and diagnostics in one boundary method.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def parse_ruby(source, dialect, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
       return unsupported_feature_result("Unsupported Ruby dialect #{dialect}.") unless dialect == 'ruby'
@@ -469,6 +486,7 @@ module Prism
         policies: []
       }
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def analyze_ruby_document(source, parse_result)
       normalized_source = prism_ruby_normalize_source(source)
@@ -485,6 +503,8 @@ module Prism
       }
     end
 
+    # Normalization builds the complete TreeHaver contract in one pass.
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def parse_ruby_normalized(source, dialect = 'ruby', backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
       return unsupported_feature_result("Unsupported Ruby dialect #{dialect}.") unless dialect == 'ruby'
@@ -566,7 +586,10 @@ module Prism
         metadata: prism_normalized_metadata
       ).to_h
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
+    # This adapter validates, edits, reparses, and reports one projection atomically.
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def apply_edit_projection(request)
       source = request.fetch(:source)
       provider_id = request.fetch(:provider_id)
@@ -638,6 +661,7 @@ module Prism
         []
       ).to_h
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     def match_ruby_owners(template, destination)
       Ruby::Merge.match_ruby_owners(template, destination)
@@ -721,6 +745,8 @@ module Prism
       end
     end
 
+    # Alias normalization intentionally handles the supported input shapes inline.
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
     def normalize_ruby_require_aliases(require_aliases)
       Array(require_aliases).each_with_object({}) do |entry, aliases|
         case entry
@@ -741,6 +767,7 @@ module Prism
         aliases[to] = canonical
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
 
     def ruby_dsl_call_node(node)
       return node if node.is_a?(::Prism::CallNode)
@@ -765,6 +792,8 @@ module Prism
       end
     end
 
+    # The reviewed merge boundary must retain all protocol roles for replay.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
     def merge_ruby_with_reviewed_nested_outputs(template_source, destination_source, dialect, review_state,
                                                 applied_children, backend: nil)
       requested = backend.to_s.empty? ? BACKEND_REFERENCE.id : backend.to_s
@@ -797,6 +826,7 @@ module Prism
         }
       )
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
 
     def merge_ruby_with_reviewed_nested_outputs_from_replay_bundle(template_source, destination_source, dialect,
                                                                    replay_bundle, backend: nil)
@@ -924,6 +954,8 @@ module Prism
       end.sort_by { |owner| owner[:path] }
     end
 
+    # Surface discovery intentionally keeps line ownership and comment state together.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def prism_ruby_discovered_surfaces(source, body)
       owners_by_line = body.filter_map do |node|
         name = prism_ruby_declaration_name(node)
@@ -954,7 +986,10 @@ module Prism
 
       surfaces
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
+    # A surface record is assembled as one schema-shaped value.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def prism_ruby_surfaces_for_owner(owner_name, comment_entries)
       filtered_entries = comment_entries.filter { |entry| prism_ruby_doc_comment_content?(entry.fetch(:raw)) }
       return [] if filtered_entries.empty?
@@ -979,7 +1014,10 @@ module Prism
 
       [doc_surface] + prism_ruby_example_surfaces(doc_surface)
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
+    # Example surfaces preserve the complete delegated-child metadata contract.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def prism_ruby_example_surfaces(surface)
       entries = Array(surface.dig(:metadata, :entries))
       Ruby::Merge::DocCommentSupport.example_blocks(entries).map do |block|
@@ -1004,6 +1042,7 @@ module Prism
         )
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def prism_ruby_declaration_name(node)
       case node
@@ -1162,6 +1201,8 @@ module Prism
       end
     end
 
+    # Comment nodes retain backend metadata in a single normalized schema value.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def prism_comment_node(source, comment, index, magic_comment, parent_id:)
       directive = prism_comment_directive(
         source.byteslice(comment.location.start_offset...comment.location.end_offset), magic_comment
@@ -1192,6 +1233,7 @@ module Prism
         }
       )
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def prism_comment_directive(comment_text, magic_comment)
       if comment_text.strip.match?(/\A#\s*smorg:freeze\b/)
@@ -1330,9 +1372,11 @@ module Prism
       :source_span_for_location
     )
   end
+  # rubocop:enable Metrics/ModuleLength
 end
 
 Prism::Merge.register_backend!
+Prism::Merge.register_provider!
 
 if defined?(Ast::Merge::RSpec::MergeGemRegistry)
   Ast::Merge::RSpec::MergeGemRegistry.register(

data/sig/prism/merge.rbs

@@ -1,5 +1,18 @@
 module Prism
   module Merge
+    class Provider
+      def provider_id: () -> String
+      def family: () -> String
+      def capabilities: () -> Ast::Merge::provider_capabilities
+      def analyze: (Ast::Merge::provider_request request) -> Ast::Merge::provider_result
+      def diff2: (Ast::Merge::provider_request request) -> Ast::Merge::provider_result
+      def merge2: (Ast::Merge::provider_request request) -> Ast::Merge::provider_result
+      def merge3: (Ast::Merge::provider_request request) -> Ast::Merge::provider_result
+    end
+
+    def self.merge_provider: () -> Provider
+    def self.register_provider!: (?replace: bool) -> Ast::Merge::_MergeProvider
+
     module Version
       VERSION: String
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prism-merge
 version: !ruby/object:Gem::Version
-  version: 7.1.1
+  version: 7.1.4
 platform: ruby
 authors:
 - Peter H. Boling
@@ -37,6 +37,20 @@ cert_chain:
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ast-merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.1.4
 - !ruby/object:Gem::Dependency
   name: prism
   requirement: !ruby/object:Gem::Requirement
@@ -57,14 +71,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.1.4
+- !ruby/object:Gem::Dependency
+  name: tree_haver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.4
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -91,20 +119,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.5.17
+        version: 3.0.7
   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.7
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -182,7 +210,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 +220,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
@@ -202,7 +230,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.19
+        version: 2.0.20
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -212,7 +240,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.19
+        version: 2.0.20
 - !ruby/object:Gem::Dependency
   name: turbo_tests2
   requirement: !ruby/object:Gem::Requirement
@@ -222,7 +250,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -232,7 +260,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.6
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -276,7 +304,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.11
+        version: 2.0.12
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -286,7 +314,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.11
+        version: 2.0.12
 description: "☯️ Prism-backed Ruby provider gem for the Structured Merge Ruby family."
 email:
 - floss@galtzo.com
@@ -330,6 +358,7 @@ files:
 - lib/prism/merge/node_wrapper.rb
 - lib/prism/merge/partial_template_merger.rb
 - lib/prism/merge/partial_template_node.rb
+- lib/prism/merge/provider.rb
 - lib/prism/merge/recursive_merge_policy.rb
 - lib/prism/merge/recursive_node_body_merger.rb
 - lib/prism/merge/ruby_doc_surface_analyzer.rb
@@ -346,10 +375,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.4
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.4/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/prism-merge/7.1.1
+  documentation_uri: https://www.rubydoc.info/gems/prism-merge/7.1.4
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/prism-merge