rbs-merge 7.1.1 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 124ffb8f50edbb602b5748527d2ac661d0a75a742e83ec7e6790970719d905ab
-  data.tar.gz: 727ce4ec649df9bc2514d965d35bb600e5ab6f6a46e7d368214c67788777ed30
+  metadata.gz: 3ff859ca9d5b341aeafadc243b34eb38be17976d5508c472d34357512790b6f2
+  data.tar.gz: 1cb7bb66b2472e9bae12c4a773cefb9d9123572f56f1bfbdb8db05fabb796947
 SHA512:
-  metadata.gz: 561f34a7ec7ea11b00df476423bd6c42f6b2e31daa84acbf3a8a24eaf05e94adc297134ece3ea1a83797dcb30f6d3d6a2758ebfc15c3d6245495b81bbffff047
-  data.tar.gz: 87968e5f4d3bdcb51b1f5a9d0a64106a265225de49361e8921f9bc97b7486537fe4c1d0fda854c79489c44406a407859bf35ae83d5392faaca1d09e5a258d67c
+  metadata.gz: 58b8b4f4fee83df915c21f86c8617f28fa3ec9b8fb4400993eb29336ac751a4141db444e9ce547e930042276d293b0bfb80859a781e672562c2b67e5fc1500bf
+  data.tar.gz: 5a2948e0f81c006710f73cfc52e15be93ee00c08ba97d6cb17a1bc67f00374d77e59a9de0efa0b0d6faf635b7f70d6b32bd53024a16889989cae0728bf74e437

data/README.md

@@ -93,7 +93,7 @@ File.write("merged.rbs", result.to_s)
 
 ### 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
@@ -442,20 +442,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/rbs/merge/provider.rb

@@ -0,0 +1,891 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Rbs
+  module Merge
+    # Base-aware, source-preserving provider for native RBS declarations.
+    # 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)
+      ExactDocument = Data.define(:source, :analysis, :declarations, :issues, :role)
+      Decision = Data.define(:changes, :conflicts, :choices)
+
+      def provider_id = 'ruby.rbs'
+      def family = 'rbs'
+
+      def capabilities
+        {
+          operations: Ast::Merge::ProviderContract::OPERATIONS,
+          dialects: %i[rbs],
+          backends: %i[rbs],
+          profiles: [DEFAULT_PROFILE],
+          role: :workflow,
+          source_preservation: %i[exact_source declaration_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: 'rbs',
+            valid: true,
+            declarations: 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)
+        merge3_request = request.merge(
+          base_source: request.fetch(:current_source),
+          ours_source: request.fetch(:current_source),
+          theirs_source: request.fetch(:incoming_source)
+        )
+        merged = merge3(merge3_request)
+        merged.merge(
+          operation: :merge2,
+          verification: merged.fetch(:verification).except(:base_participated)
+        )
+      end
+
+      def merge3(request)
+        exact_role = exact_revision_role(request)
+        return merge3_exact(request, exact_role) if exact_role
+
+        documents = parse_merge3_documents(request)
+        return documents if provider_failure?(documents)
+
+        decision = decide(documents, include_unmanaged_conflict: true)
+        return render_conflicts(request, documents, decision) unless decision.conflicts.empty?
+
+        render_composite(request, documents, decision)
+      end
+
+      private
+
+      def parse_merge3_documents(request)
+        %i[base ours theirs].each_with_object({}) do |role, documents|
+          source = request.fetch(:"#{role}_source")
+          document = parse_source(source, role)
+          if document.is_a?(Hash) && document[:parse_error]
+            return parse_failure(:merge3, request, role, document)
+          elsif provider_failure?(document)
+            return unsafe_document_failure(request, role, document)
+          end
+
+          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 = TreeHaver.with_backend(:rbs) { FileAnalysis.new(source) }
+        unless analysis.errors.empty? && analysis.backend == :rbs
+          return { parse_error: analysis.errors.map(&:to_s).join('; '), source_role: role }
+        end
+
+        owners = analysis.declarations.map do |declaration|
+          wrapper = NodeWrapper.new(
+            declaration,
+            lines: source.split("\n", -1),
+            source: source,
+            backend: :rbs
+          )
+          return { unsafe_range: wrapper.signature, source_role: role } unless safe_range?(source, declaration.location)
+
+          signature = wrapper.signature
+          Owner.new(
+            id: owner_id(signature),
+            signature: signature,
+            fingerprint: owner_fingerprint(source, declaration),
+            start_line: wrapper.start_line,
+            end_line: wrapper.end_line,
+            role: role
+          )
+        end
+        duplicate = owners.group_by(&:id).find { |_id, matches| matches.length > 1 }
+        return { ambiguous_owner: duplicate.first, source_role: role } if duplicate
+        return { unsafe_range: :overlapping_declarations, source_role: role } unless non_overlapping?(owners)
+
+        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)
+        )
+      rescue StandardError => e
+        { parse_error: e.message, source_role: role }
+      end
+
+      def parse_exact_source(source, role)
+        analysis = TreeHaver.with_backend(:rbs) { FileAnalysis.new(source) }
+        unless analysis.errors.empty? && analysis.backend == :rbs
+          return { parse_error: analysis.errors.map(&:to_s).join('; '), source_role: role }
+        end
+
+        declarations = analysis.declarations.map do |declaration|
+          wrapper = NodeWrapper.new(
+            declaration,
+            lines: source.split("\n", -1),
+            source: source,
+            backend: :rbs
+          )
+          [wrapper.signature, semantic_attributes(declaration)]
+        end.freeze
+        duplicate = declarations.group_by(&:first).find { |_signature, matches| matches.length > 1 }
+        issues = if duplicate
+                   [{
+                     category: :ambiguous_owner,
+                     declaration: duplicate.first,
+                     message: duplicate_message(duplicate.first)
+                   }]
+                 else
+                   []
+                 end
+        ExactDocument.new(
+          source: source,
+          analysis: analysis,
+          declarations: declarations,
+          issues: issues.freeze,
+          role: role
+        )
+      rescue StandardError => e
+        { parse_error: e.message, source_role: role }
+      end
+
+      def safe_range?(source, location)
+        return false unless location
+        return false unless location.start_line.positive? && location.end_line >= location.start_line
+        return false unless location.start_column.zero?
+        return false if location.start_pos.negative? || location.end_pos > source.bytesize
+
+        line_end = source.index("\n", location.end_pos) || source.bytesize
+        source.byteslice(location.end_pos...line_end).to_s.each_byte.all? { |byte| [9, 13, 32].include?(byte) }
+      end
+
+      def non_overlapping?(owners)
+        owners.each_cons(2).all? { |left, right| left.end_line < right.start_line }
+      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_attributes(value)
+        case value
+        when Array
+          value.map { |item| semantic_attributes(item) }
+        when Hash
+          value.map { |key, item| [semantic_attributes(key), semantic_attributes(item)] }
+        when String, Symbol, Numeric, true, false, nil
+          value
+        else
+          attributes = value.instance_variables.reject { |name| %i[@location @comment].include?(name) }
+          [
+            value.class.name,
+            attributes.map { |name| [name, semantic_attributes(value.instance_variable_get(name))] }
+          ]
+        end
+      end
+
+      def owner_fingerprint(source, declaration)
+        location = declaration.location
+        exact_source = source.byteslice(location.start_pos...location.end_pos)
+        Digest::SHA256.hexdigest(JSON.generate(Ast::Merge.json_ready([semantic_attributes(declaration), exact_source])))
+      end
+
+      def owner_id(signature)
+        Digest::SHA256.hexdigest(JSON.generate(Ast::Merge.json_ready(signature)))
+      end
+
+      def owner_path(owner)
+        owner ? owner.signature.inspect : '<document>'
+      end
+
+      def owner_description(owner)
+        {
+          path: owner_path(owner),
+          signature: owner.signature,
+          source_role: owner.role,
+          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 equivalent?(left, right)
+
+          {
+            path: owner_path(left || right),
+            before: change_side(left),
+            after: change_side(right),
+            change: change_kind(left, right)
+          }.freeze
+        end.freeze
+      end
+
+      def change_side(owner)
+        return { present: false } unless owner
+
+        { present: true, source_role: owner.role, line_range: [owner.start_line, owner.end_line] }
+      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 = {}
+        if include_unmanaged_conflict
+          append_unmanaged_conflict(changes, conflicts, documents)
+          append_directive_conflict(changes, conflicts, documents)
+        end
+        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
+
+        change = {
+          path: '<unmanaged-source>',
+          ours: base == ours ? :unchanged : :edited,
+          theirs: base == theirs ? :unchanged : :edited
+        }.freeze
+        changes << change
+        conflicts << {
+          conflict_id: "rbs-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 append_directive_conflict(changes, conflicts, documents)
+        return unless documents.values.any? { |document| document.analysis.directives.any? }
+
+        change = { path: '<directives>', ours: :unsafe, theirs: :unsafe }.freeze
+        changes << change
+        conflicts << {
+          conflict_id: "rbs-directives-#{Digest::SHA256.hexdigest(documents.values.map(&:source).join("\0"))[0, 16]}",
+          category: :unsafe_directives,
+          path: change.fetch(:path),
+          owner_id: nil,
+          change_classification: change
+        }.freeze
+      end
+
+      def side_change(base, side)
+        return :unchanged if equivalent?(base, side)
+        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 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: "rbs-declaration-#{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,
+          source_role: owner&.role,
+          line_range: owner && [owner.start_line, owner.end_line]
+        }
+      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 merge3_exact(request, role)
+        documents = %i[base ours theirs].to_h do |source_role|
+          [source_role, parse_exact_source(request.fetch(:"#{source_role}_source"), source_role)]
+        end
+        winner = documents.fetch(role)
+        return parse_failure(:merge3, request, role, winner) if provider_failure?(winner)
+
+        render_exact(request, documents, role)
+      end
+
+      def render_exact(request, documents, role)
+        winner = documents.fetch(role)
+        rendered = render_plan(request, [whole_source_fragment(role, request.fetch(:"#{role}_source"))])
+        verification = verify_exact_rendered(rendered.content, winner)
+        unless verification[:semantic_match] && verification[:byte_exact]
+          return failure(
+            :merge3,
+            request,
+            category: :render_failure,
+            message: 'RBS exact revision did not remain byte-exact and semantically identical after native reparse.',
+            source_role: role,
+            render_report: render_report(rendered, :exact_revision),
+            verification: verification.merge(base_participated: true)
+          )
+        end
+
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          diagnostics: exact_diagnostics(documents),
+          render_report: render_report(rendered, :exact_revision),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def verify_exact_rendered(output, expected)
+        parsed = parse_exact_source(output, :output)
+        if provider_failure?(parsed)
+          return {
+            output_reparsed: false,
+            byte_exact: output == expected.source,
+            semantic_match: false,
+            parse_error: failure_detail(parsed),
+            source_role: expected.role
+          }
+        end
+
+        actual_signatures = parsed.declarations.map(&:first)
+        expected_signatures = expected.declarations.map(&:first)
+        actual_attributes = parsed.declarations.map(&:last)
+        expected_attributes = expected.declarations.map(&:last)
+        {
+          output_reparsed: true,
+          byte_exact: output == expected.source,
+          semantic_match: parsed.declarations == expected.declarations,
+          ordered_declaration_signatures_verified: actual_signatures == expected_signatures,
+          ast_attributes_verified: actual_attributes == expected_attributes,
+          planned_declaration_count: expected.declarations.length,
+          output_declaration_count: parsed.declarations.length,
+          source_role: expected.role
+        }
+      end
+
+      def exact_diagnostics(documents)
+        documents.flat_map do |role, document|
+          if provider_failure?(document)
+            [{
+              category: :parse_error,
+              severity: :warning,
+              message: "#{role} parse error: #{failure_detail(document)}",
+              blocking: false,
+              source_role: role
+            }]
+          else
+            document.issues.map do |issue|
+              issue.merge(severity: :warning, blocking: false, source_role: role).freeze
+            end
+          end
+        end.freeze
+      end
+
+      def duplicate_message(signature)
+        "ambiguous duplicate declaration #{signature.inspect}"
+      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)
+        unless verification[:semantic_match]
+          return failure(
+            :merge3,
+            request,
+            category: :render_failure,
+            message: 'RBS composite did not match the planned ordered declaration structure and AST attributes.',
+            changes: decision.changes,
+            render_report: render_report(rendered, :exact_declaration_composite),
+            verification: verification.merge(base_participated: true)
+          )
+        end
+
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: decision.changes,
+          render_report: render_report(rendered, :exact_declaration_composite),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def composite_fragments(documents, decision)
+        ours = documents.fetch(:ours)
+        fragments = []
+        cursor = 1
+        replacement_edits(documents, decision).sort_by { |edit| edit.fetch(:start_line) }.each do |edit|
+          append_range(fragments, :ours, cursor, edit.fetch(:start_line) - 1)
+          append_owner(fragments, edit[:owner]) if edit[:owner]
+          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
+          next if role == :ours
+
+          {
+            start_line: ours_owner.start_line,
+            end_line: ours_owner.end_line,
+            owner: role && documents.fetch(role).by_id[id]
+          }
+        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: :declaration_separator,
+          producer: provider_id,
+          metadata: { source_role: fragment.respond_to?(:revision) ? fragment.revision : nil, 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)
+        parsed = parse_source(output, :output)
+        if provider_failure?(parsed)
+          return {
+            output_reparsed: false,
+            semantic_match: false,
+            parse_error: failure_detail(parsed)
+          }
+        end
+
+        actual = parsed.owners.map { |owner| [owner.signature, owner.fingerprint] }
+        planned = expected.map { |owner| [owner.signature, owner.fingerprint] }
+        {
+          output_reparsed: true,
+          semantic_match: actual == planned,
+          ordered_declaration_signatures_verified: actual.map(&:first) == planned.map(&:first),
+          ast_attributes_verified: actual.map(&:last) == planned.map(&:last),
+          planned_declaration_count: planned.length,
+          output_declaration_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, :declaration_localized_conflict)
+        end
+
+        rendered = render_plan(request, [whole_document_conflict(request, decision)])
+        conflict_failure(
+          request,
+          decision,
+          rendered,
+          :full_file_conflict,
+          fallbacks: [{ from: :declaration_localization, to: :full_file_conflict, reason: :source_ownership_unproven }]
+        )
+      end
+
+      def localized_conflict_fragments(request, documents, decision)
+        return if decision.conflicts.any? { |conflict| conflict[:owner_id].nil? }
+
+        ours = documents.fetch(:ours)
+        return unless decision.conflicts.all? { |conflict| ours.by_id.key?(conflict.fetch(:owner_id)) }
+
+        ranges = decision.conflicts.map { |conflict| [conflict, ours.by_id.fetch(conflict.fetch(:owner_id))] }
+        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 << declaration_conflict_fragment(request, documents, conflict)
+          cursor = owner.end_line + 1
+        end
+        append_range(fragments, :ours, cursor, ours.source.lines.length)
+        fragments
+      end
+
+      def declaration_conflict_fragment(request, documents, conflict)
+        Ast::Merge::SourceRender::ConflictFragment.new(
+          conflict_id: conflict.fetch(:conflict_id),
+          base: conflict_declaration_side(documents, conflict, :base),
+          ours: conflict_declaration_side(documents, conflict, :ours),
+          theirs: conflict_declaration_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_declaration_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 unsafe_document_failure(request, role, parsed)
+        return parsed unless parsed[:unsafe_range] || parsed[:ambiguous_owner]
+
+        conflict_id = "rbs-unsafe-#{Digest::SHA256.hexdigest([role, failure_detail(parsed)].join("\0"))[0, 16]}"
+        conflict = {
+          conflict_id: conflict_id,
+          category: parsed[:ambiguous_owner] ? :ambiguous_owner : :unsafe_source_range,
+          path: '<document>',
+          owner_id: nil,
+          source_role: role
+        }
+        rendered = render_plan(
+          request,
+          [whole_document_conflict(request, Decision.new(changes: [], conflicts: [conflict], choices: {}))]
+        )
+        failure(
+          :merge3,
+          request,
+          category: conflict.fetch(:category),
+          message: "#{role} cannot be merged safely: #{failure_detail(parsed)}",
+          conflicts: [conflict],
+          conflicted_output: rendered.content,
+          source_role: role,
+          render_report: render_report(rendered, :full_file_conflict),
+          verification: { base_participated: true }
+        )
+      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")
+
+        synthesized_copy("#{fragment_source}\n", :conflict_line_boundary, owner.role)
+      end
+
+      def conflict_whole_source_fragment(role, source)
+        return whole_source_fragment(role, source) if source.empty? || source.end_with?("\n")
+
+        synthesized_copy("#{source}\n", :conflict_line_boundary, role)
+      end
+
+      def synthesized_copy(content, reason, role)
+        Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: content,
+          reason: reason,
+          producer: provider_id,
+          metadata: { source_role: role, copied_source: true }
+        )
+      end
+
+      def whole_source_fragment(role, source)
+        return synthesized_copy('', :exact_empty_source, role) if source.empty?
+
+        source_range_fragment(role, 1, source.lines.length)
+      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: 'RBS top-level declaration 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 parse_failure(operation, request, role, parsed)
+        category = if parsed[:parse_error]
+                     :parse_error
+                   elsif parsed[:ambiguous_owner]
+                     :ambiguous_owner
+                   else
+                     :unsafe_source_range
+                   end
+        failure(
+          operation,
+          request,
+          category: category,
+          message: "#{role} parse error: #{failure_detail(parsed)}",
+          source_role: role
+        )
+      end
+
+      def failure_detail(parsed)
+        return parsed[:parse_error] if parsed[:parse_error]
+        return "ambiguous duplicate declaration #{parsed[:ambiguous_owner].inspect}" if parsed[:ambiguous_owner]
+
+        "unsafe declaration range #{parsed[:unsafe_range].inspect}"
+      end
+
+      def provider_failure?(value)
+        value.is_a?(Hash) &&
+          (value[:ok] == false || value.key?(:parse_error) || value.key?(:ambiguous_owner) || value.key?(:unsafe_range))
+      end
+
+      def result(operation, request, changes: [], diagnostics: [], render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: true,
+          envelope: envelope(
+            request,
+            changes: changes,
+            diagnostics: diagnostics,
+            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] || :rbs,
+            backend: request[:backend] || :rbs,
+            package: 'rbs-merge',
+            package_version: Rbs::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/rbs/merge/version.rb

@@ -5,7 +5,7 @@ module Rbs
     # 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/rbs/merge.rb

@@ -137,12 +137,23 @@ module Rbs
         backends << TREE_SITTER_BACKEND_REFERENCE if registrations.key?(:tree_sitter) || registrations.key?(:tslp)
         backends
       end
+
+      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
 
+Rbs::Merge.autoload :Provider, 'rbs/merge/provider'
+
 # Register the RBS backend with TreeHaver when this gem is loaded
 Rbs::Merge.register_backend!
+Rbs::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/rbs/merge.rbs

@@ -1,5 +1,18 @@
 module Rbs
   module Merge
+    class Provider
+      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
+
+    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: rbs-merge
 version: !ruby/object:Gem::Version
-  version: 7.1.1
+  version: 7.1.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -43,14 +43,14 @@ 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: rbs
   requirement: !ruby/object:Gem::Requirement
@@ -71,14 +71,14 @@ 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: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -105,20 +105,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
@@ -196,7 +196,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
@@ -206,7 +206,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
@@ -236,7 +236,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
@@ -246,7 +246,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
@@ -323,6 +323,7 @@ files:
 - lib/rbs/merge/merge_result.rb
 - lib/rbs/merge/node_type_normalizer.rb
 - lib/rbs/merge/node_wrapper.rb
+- lib/rbs/merge/provider.rb
 - lib/rbs/merge/smart_merger.rb
 - lib/rbs/merge/version.rb
 - sig/rbs/merge.rbs
@@ -332,10 +333,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/rbs-merge/7.1.1
+  documentation_uri: https://www.rubydoc.info/gems/rbs-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/rbs-merge