json-merge 7.1.1 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8464cc00eee820f30fa56722aba993b0f661a3521c185da21e90035cc9dc967f
-  data.tar.gz: b70e0d898ba77416611c0b58280b68ec08431119c07ca154cf6e0e565b086b37
+  metadata.gz: ff5d2c1fa09edee00c444aedc35377b040f6dc6e07ae160e31243ffa07ebbe70
+  data.tar.gz: 8601741a2313c127bb861081460a4ae6e817f247f804e78721a162dfeeb2010b
 SHA512:
-  metadata.gz: cd3daa1695fff2cb7fab9287253f714efc90a5eb4502d6d545394326c44fa151e507375cb302bb0ddce1e998287c348d7feaa724b2aaf8835a6e175639dfe35c
-  data.tar.gz: 4314f63422ccb37ecceb31d576d9593195a1f2ace7ba0ddc019eb96419841a52ae816732ec208d1776465c4ee961b4cdf363d8b21e5735ebb25061413a4a0361
+  metadata.gz: ce19e05de329325e569cca1b0fbb80a4933ff2b8a690bcabf8d68111202793f46fc16f6c1434c01497b607d1e5d1440bb13d4e923ab4b1f941a08faf99706037
+  data.tar.gz: 0eba7ac69972809823b4478640a66e49b068829a830066fb9c00465298cba8d0b9c23b7cfb4ebd04e582f3aa0f086289fe84efaa4da777d7b4c3026df7d3199d

data/README.md

@@ -107,7 +107,7 @@ File.write("merged.json", result.to_json)
 
 ### 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
@@ -433,20 +433,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/json/merge/provider.rb

@@ -0,0 +1,696 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Portable JSON-family provider for Ast::Merge dispatch.
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- provider operations keep request, rendering, and result-envelope logic together
+    class Provider
+      DIALECTS = %i[json jsonc json5].freeze
+      DEFAULT_PROFILE = :source_preserving
+
+      def provider_id
+        'ruby.json'
+      end
+
+      def family
+        'json'
+      end
+
+      def capabilities
+        {
+          operations: Ast::Merge::ProviderContract::OPERATIONS,
+          dialects: DIALECTS,
+          backends: [Json::Merge::TREE_SITTER_BACKEND.id.to_sym],
+          profiles: [DEFAULT_PROFILE],
+          role: :workflow,
+          source_preservation: %i[exact_source family_synthesis line_provenance reparse]
+        }.freeze
+      end
+
+      def analyze(request)
+        dialect = dialect_for(request)
+        parsed = Json::Merge.parse_json(request.fetch(:source), dialect, backend: request[:backend])
+        return parse_failure(:analyze, :source, parsed, request) unless parsed[:ok]
+
+        result(
+          :analyze,
+          request,
+          analysis: parsed.fetch(:analysis),
+          verification: { source_parsed: true }
+        )
+      end
+
+      def diff2(request)
+        before = parse_role!(:diff2, request, :before)
+        return before if provider_failure?(before)
+
+        after = parse_role!(:diff2, request, :after)
+        return after if provider_failure?(after)
+
+        changes = diff_values(before, after, path: '')
+        result(
+          :diff2,
+          request,
+          diff: { changes: changes, before: before, after: after },
+          changes: changes,
+          verification: { before_parsed: true, after_parsed: true }
+        )
+      end
+
+      def merge2(request)
+        dialect = dialect_for(request)
+        merged = Json::Merge.merge_json(
+          request.fetch(:incoming_source),
+          request.fetch(:current_source),
+          dialect,
+          backend: request[:backend]
+        )
+        return merge2_failure(merged, request) unless merged[:ok]
+
+        output = merged.fetch(:output)
+        verified = parse_output(output, request)
+        result(
+          :merge2,
+          request,
+          output: output,
+          changes: [],
+          render_report: { strategy: :json_smart_merger, synthesis: :family_emission },
+          verification: { output_reparsed: true, semantic_value: verified }
+        )
+      rescue Json::Merge::ParseError => e
+        failure(
+          :merge2,
+          request,
+          category: :render_failure,
+          message: "JSON family emitter produced invalid output: #{e.message}"
+        )
+      end
+
+      def merge3(request)
+        values = parse_merge3_roles(request)
+        return values if provider_failure?(values)
+
+        decision = ThreeWayDecision.new.call(**values)
+        rendered = render_merge3(decision, request, values)
+        return rendered if provider_failure?(rendered)
+
+        result(
+          :merge3,
+          request,
+          **rendered,
+          changes: decision.changes,
+          conflicts: decision.conflicts,
+          verification: rendered.fetch(:verification).merge(base_participated: true)
+        )
+      end
+
+      private
+
+      def parse_merge3_roles(request)
+        %i[base ours theirs].each_with_object({}) do |role, values|
+          parsed = parse_role!(:merge3, request, role)
+          return parsed if provider_failure?(parsed)
+
+          values[role] = parsed
+        end
+      end
+
+      def parse_role!(operation, request, role)
+        Json::Merge.json_value_for_source(
+          request.fetch(:"#{role}_source"),
+          dialect: dialect_for(request),
+          backend: request[:backend]
+        )
+      rescue Json::Merge::ParseError => e
+        failure(
+          operation,
+          request,
+          category: :parse_error,
+          message: "#{role} parse error: #{e.message}",
+          source_role: role
+        )
+      end
+
+      def render_merge3(decision, request, values)
+        return render_conflict(request, decision) if decision.conflicted?
+
+        exact_role = %i[ours theirs base].find { |role| values.fetch(role) == decision.value }
+        return render_exact_role(exact_role, request, decision) if exact_role
+
+        render_composite(request, decision)
+      end
+
+      def diff_values(before, after, path:)
+        return [] if before == after
+        return diff_objects(before, after, path: path) if before.is_a?(Hash) && after.is_a?(Hash)
+
+        [{ path: path, ours: :unchanged, theirs: :edited }.freeze]
+      end
+
+      def diff_objects(before, after, path:)
+        ordered_diff_keys(before, after).flat_map do |key|
+          child_path = "#{path}/#{escape_path_segment(key)}"
+          if !before.key?(key)
+            [{ path: child_path, ours: :unchanged, theirs: :added }.freeze]
+          elsif !after.key?(key)
+            [{ path: child_path, ours: :unchanged, theirs: :deleted }.freeze]
+          else
+            diff_values(before.fetch(key), after.fetch(key), path: child_path)
+          end
+        end.freeze
+      end
+
+      def ordered_diff_keys(before, after)
+        [*before.keys, *after.keys].uniq
+      end
+
+      def escape_path_segment(key)
+        key.to_s.gsub('~', '~0').gsub('/', '~1')
+      end
+
+      def render_exact_role(role, request, decision)
+        rendered = render_plan(
+          request,
+          [
+            source_fragment(role, request.fetch(:"#{role}_source"))
+          ]
+        )
+        {
+          output: rendered.content,
+          render_report: render_report(rendered, strategy: :exact_revision),
+          verification: verify_rendered(rendered.content, decision.value, request)
+        }
+      end
+
+      def render_composite(request, decision)
+        candidate = Json::Merge.merge_json(
+          request.fetch(:theirs_source),
+          request.fetch(:ours_source),
+          dialect_for(request),
+          backend: request[:backend]
+        )
+        emitted = verified_family_composite(candidate, request, decision)
+        return emitted if emitted
+
+        exact = render_exact_composite(request, decision)
+        return exact if exact
+
+        composite_failure(request, 'JSON family renderers did not reproduce the planned three-way value.')
+      end
+
+      def verified_family_composite(candidate, request, decision)
+        return unless candidate[:ok]
+
+        output = candidate.fetch(:output)
+        verification = verify_rendered(output, decision.value, request)
+        return unless verification[:semantic_match]
+
+        rendered = render_plan(
+          request,
+          [
+            Ast::Merge::SourceRender::SynthesizedFragment.new(
+              content: output,
+              reason: :family_emission,
+              producer: provider_id
+            )
+          ]
+        )
+        {
+          output: rendered.content,
+          render_report: render_report(rendered, strategy: :family_composite),
+          verification: verification
+        }
+      end
+
+      def render_exact_composite(request, decision)
+        replacements = exact_composite_replacements(request, decision)
+        return unless replacements
+
+        rendered = render_plan(request, replacement_fragments(request, replacements))
+        verification = verify_rendered(rendered.content, decision.value, request)
+        return unless verification[:semantic_match]
+
+        {
+          output: rendered.content,
+          render_report: render_report(rendered, strategy: :exact_owner_composite),
+          fallbacks: [
+            {
+              from: :family_composite,
+              to: :exact_owner_composite,
+              reason: :semantic_verification_failed
+            }
+          ],
+          verification: verification
+        }
+      end
+
+      def exact_composite_replacements(request, decision)
+        locators = conflict_locators(request)
+        changes = decision.changes.select do |change|
+          change[:ours] == :unchanged && change[:theirs] != :unchanged
+        end
+        replacements = []
+        until changes.empty?
+          change = changes.shift
+          ours_range = locators.fetch(:ours).pair_range(change.fetch(:path))
+          return unless ours_range
+
+          theirs_range = if change[:theirs] == :deleted
+                           nil
+                         else
+                           locators.fetch(:theirs).pair_range(change.fetch(:path))
+                         end
+          return if change[:theirs] != :deleted && theirs_range.nil?
+
+          replacements << { ours: ours_range, theirs: theirs_range }
+        end
+        return unless non_overlapping_ours_ranges?(replacements)
+
+        replacements
+      end
+
+      def replacement_fragments(request, replacements)
+        fragments = []
+        cursor = 1
+        replacements.sort_by { |item| item.fetch(:ours).start_line }.each do |item|
+          ours_range = item.fetch(:ours)
+          fragments << source_range_fragment(:ours, cursor, ours_range.start_line - 1) if cursor < ours_range.start_line
+          theirs_range = item[:theirs]
+          fragments << source_range_fragment(:theirs, theirs_range.start_line, theirs_range.end_line) if theirs_range
+          cursor = ours_range.end_line + 1
+        end
+        final_line = request.fetch(:ours_source).lines.length
+        fragments << source_range_fragment(:ours, cursor, final_line) if cursor <= final_line
+        fragments
+      end
+
+      def render_conflict(request, decision)
+        localized = localized_conflict_plan(request, decision)
+        return localized if localized
+
+        synthesized = synthesized_conflict_plan(request, decision)
+        return synthesized if synthesized
+
+        render_full_file_conflict(request, decision)
+      end
+
+      def localized_conflict_plan(request, decision)
+        ranges = localized_conflict_ranges(request, decision)
+        return if ranges.nil?
+
+        rendered = render_plan(request, localized_conflict_fragments(request, decision, ranges))
+        conflict_failure(request, decision, rendered, strategy: :owner_localized_conflict)
+      end
+
+      def localized_conflict_ranges(request, decision)
+        locators = conflict_locators(request)
+        ranges = decision.conflicts.map do |conflict|
+          conflict_ranges(conflict, locators)
+        end
+        return if ranges.any?(&:nil?)
+        return unless non_overlapping_ours_ranges?(ranges)
+
+        ranges
+      end
+
+      def synthesized_conflict_plan(request, decision)
+        candidate = Json::Merge.merge_json(
+          request.fetch(:theirs_source),
+          request.fetch(:ours_source),
+          dialect_for(request),
+          backend: request[:backend]
+        )
+        return unless candidate[:ok]
+        return unless verify_rendered(candidate.fetch(:output), decision.value, request)[:semantic_match]
+
+        ranges = synthesized_conflict_ranges(request, decision, candidate.fetch(:output))
+        return unless ranges
+
+        rendered = render_plan(
+          request,
+          synthesized_conflict_fragments(request, decision, candidate.fetch(:output), ranges)
+        )
+        conflict_failure(
+          request,
+          decision,
+          rendered,
+          strategy: :synthesized_owner_localized_conflict,
+          fallbacks: [
+            {
+              from: :exact_owner_localization,
+              to: :synthesized_conflict_context,
+              reason: :missing_side_owner
+            }
+          ]
+        )
+      end
+
+      def synthesized_conflict_ranges(request, decision, candidate)
+        locators = conflict_locators(request)
+        candidate_locator = SourceLocator.new(
+          candidate,
+          dialect: dialect_for(request),
+          backend: request[:backend]
+        )
+        conflicts = decision.conflicts.dup
+        ranges = []
+        until conflicts.empty?
+          conflict = conflicts.shift
+          sides = conflict_source_ranges(conflict, locators)
+          context = candidate_locator.pair_range(conflict.fetch(:path))
+          return unless sides && context
+
+          ranges << sides.merge(context: context)
+        end
+        return unless non_overlapping_ranges?(ranges.map { |item| item.fetch(:context) })
+
+        ranges
+      end
+
+      def conflict_source_ranges(conflict, locators)
+        ranges = {}
+        roles = %i[base ours theirs]
+        until roles.empty?
+          role = roles.shift
+          state = conflict.fetch(role)
+          range = state.fetch(:present) ? locators.fetch(role).pair_range(conflict.fetch(:path)) : nil
+          return if state.fetch(:present) && range.nil?
+
+          ranges[role] = range
+        end
+        ranges
+      end
+
+      def synthesized_conflict_fragments(request, decision, candidate, ranges)
+        fragments = []
+        cursor = 1
+        decision.conflicts
+                .zip(ranges)
+                .sort_by { |_conflict, item| item.fetch(:context).start_line }
+                .each do |conflict, item|
+                  context = item.fetch(:context)
+                  append_synthesized_context(fragments, candidate, cursor, context.start_line - 1)
+                  fragments << conflict_fragment(request, conflict, item)
+                  cursor = context.end_line + 1
+                end
+        append_synthesized_context(fragments, candidate, cursor, candidate.lines.length)
+        fragments
+      end
+
+      def append_synthesized_context(fragments, source, start_line, end_line)
+        return if start_line > end_line
+
+        content = source.lines.slice(start_line - 1, end_line - start_line + 1).join
+        fragments << Ast::Merge::SourceRender::SynthesizedFragment.new(
+          content: content,
+          reason: :conflict_context,
+          producer: provider_id,
+          metadata: { candidate_line_start: start_line }
+        )
+      end
+
+      def conflict_locators(request)
+        %i[base ours theirs].to_h do |role|
+          [
+            role,
+            SourceLocator.new(
+              request.fetch(:"#{role}_source"),
+              dialect: dialect_for(request),
+              backend: request[:backend]
+            )
+          ]
+        end
+      end
+
+      def conflict_ranges(conflict, locators)
+        ranges = {}
+        roles = %i[base ours theirs]
+        until roles.empty?
+          role = roles.shift
+          state = conflict.fetch(role)
+          range = state.fetch(:present) ? locators.fetch(role).pair_range(conflict.fetch(:path)) : nil
+          return if state.fetch(:present) && range.nil?
+
+          ranges[role] = range
+        end
+        return if ranges[:ours].nil?
+
+        ranges
+      end
+
+      def non_overlapping_ours_ranges?(ranges)
+        non_overlapping_ranges?(ranges.map { |item| item.fetch(:ours) })
+      end
+
+      def non_overlapping_ranges?(ranges)
+        ranges
+          .sort_by(&:start_line)
+          .each_cons(2)
+          .none? { |left, right| left.end_line >= right.start_line }
+      end
+
+      def localized_conflict_fragments(request, decision, ranges)
+        fragments = []
+        cursor = 1
+        decision.conflicts
+                .zip(ranges)
+                .sort_by { |_conflict, item| item.fetch(:ours).start_line }
+                .each do |conflict, item|
+                  ours_range = item.fetch(:ours)
+                  if cursor < ours_range.start_line
+                    fragments << source_range_fragment(:ours, cursor, ours_range.start_line - 1)
+                  end
+                  fragments << conflict_fragment(request, conflict, item)
+                  cursor = ours_range.end_line + 1
+                end
+        final_line = request.fetch(:ours_source).lines.length
+        fragments << source_range_fragment(:ours, cursor, final_line) if cursor <= final_line
+        fragments
+      end
+
+      def conflict_fragment(request, conflict, ranges)
+        Ast::Merge::SourceRender::ConflictFragment.new(
+          conflict_id: conflict.fetch(:conflict_id),
+          base: conflict_side_fragment(:base, ranges[:base]),
+          ours: conflict_side_fragment(:ours, ranges[:ours]),
+          theirs: conflict_side_fragment(:theirs, ranges[: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_side_fragment(role, range)
+        range ? [source_range_fragment(role, range.start_line, range.end_line)] : []
+      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_full_file_conflict(request, decision)
+        rendered = render_plan(
+          request,
+          [
+            Ast::Merge::SourceRender::ConflictFragment.new(
+              conflict_id: decision.conflicts.first.fetch(:conflict_id),
+              base: [conflict_source_fragment(:base, request.fetch(:base_source))],
+              ours: [conflict_source_fragment(:ours, request.fetch(:ours_source))],
+              theirs: [conflict_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] } }
+            )
+          ]
+        )
+        conflict_failure(
+          request,
+          decision,
+          rendered,
+          strategy: :full_file_conflict,
+          fallbacks: [
+            {
+              from: :owner_localization,
+              to: :full_file_conflict,
+              reason: :owner_not_whole_line_addressable
+            }
+          ]
+        )
+      end
+
+      def conflict_failure(request, decision, rendered, strategy:, fallbacks: [])
+        failure(
+          :merge3,
+          request,
+          category: :merge_conflict,
+          message: "#{decision.conflicts.length} unresolved JSON merge conflict(s).",
+          changes: decision.changes,
+          conflicts: decision.conflicts,
+          fallbacks: fallbacks,
+          conflicted_output: rendered.content,
+          render_report: render_report(rendered, strategy: strategy)
+        )
+      end
+
+      def render_plan(request, fragments)
+        plan = 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, dialect: dialect_for(request) }
+        )
+        Ast::Merge::SourceRender::Renderer.new.render(plan)
+      end
+
+      def source_fragment(role, source)
+        line_count = source.lines.length
+        raise Ast::Merge::SourceRender::InvalidPlanError, "#{role} source has no renderable lines" if line_count.zero?
+
+        Ast::Merge::SourceRender::SourceFragment.new(
+          revision: role,
+          start_line: 1,
+          end_line: line_count,
+          metadata: { source_role: role }
+        )
+      end
+
+      def conflict_source_fragment(role, source)
+        return source_fragment(role, source) if 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 verify_rendered(output, expected_value, request)
+        actual = parse_output(output, request)
+        {
+          output_reparsed: true,
+          semantic_match: actual == expected_value
+        }
+      rescue Json::Merge::ParseError
+        {
+          output_reparsed: false,
+          semantic_match: false
+        }
+      end
+
+      def parse_output(output, request)
+        Json::Merge.json_value_for_source(
+          output,
+          dialect: dialect_for(request),
+          backend: request[:backend]
+        )
+      end
+
+      def result(
+        operation, request, verification:, changes: [], conflicts: [], fallbacks: [], render_report: {}, **payload
+      )
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: true,
+          envelope: {
+            provider: provider_metadata(request),
+            profile: profile_metadata(request),
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            render_report: render_report,
+            verification: verification
+          },
+          **payload
+        )
+      end
+
+      def failure(
+        operation, request, category:, message:, changes: [], conflicts: [], fallbacks: [], render_report: {}, **payload
+      )
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: false,
+          envelope: {
+            provider: provider_metadata(request),
+            profile: profile_metadata(request),
+            diagnostics: [{ category: category, severity: :error, message: message, blocking: true }],
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            render_report: render_report,
+            verification: { base_participated: operation == :merge3 }
+          },
+          **payload
+        )
+      end
+
+      def parse_failure(operation, role, parsed, request)
+        diagnostic = parsed.fetch(:diagnostics).first || {}
+        failure(
+          operation,
+          request,
+          category: :parse_error,
+          message: "#{role} parse error: #{diagnostic[:message]}",
+          source_role: role
+        )
+      end
+
+      def merge2_failure(merged, request)
+        diagnostic = merged.fetch(:diagnostics).first || {}
+        failure(
+          :merge2,
+          request,
+          category: diagnostic[:category] || :merge_failed,
+          message: diagnostic[:message] || 'JSON two-way merge failed.'
+        )
+      end
+
+      def composite_failure(request, message)
+        failure(:merge3, request, category: :render_failure, message: message)
+      end
+
+      def provider_failure?(value)
+        value.is_a?(Hash) && value[:ok] == false
+      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 provider_metadata(request)
+        {
+          provider_id: provider_id,
+          family: family,
+          dialect: dialect_for(request),
+          backend: request[:backend],
+          package: Json::Merge::PACKAGE_NAME,
+          package_version: Json::Merge::Version::VERSION
+        }.compact
+      end
+
+      def profile_metadata(request)
+        { profile_id: request[:profile_id] || DEFAULT_PROFILE }
+      end
+
+      def dialect_for(request)
+        (request[:dialect] || :json).to_sym
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+  end
+end

data/lib/json/merge/source_locator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Locates JSON object-pair owners that can be copied as whole source lines.
+    class SourceLocator
+      Range = Data.define(:start_line, :end_line)
+
+      def initialize(source, dialect:, backend: nil)
+        @source = source
+        @lines = source.lines
+        Json::Merge.register_backend!
+        backend_id = backend.to_s.empty? ? Json::Merge::TREE_SITTER_BACKEND.id : backend.to_s
+        @analysis = TreeHaver.with_backend(backend_id) do
+          FileAnalysis.new(source, dialect: dialect)
+        end
+      end
+
+      def pair_range(path)
+        pair = pair_for(path)
+        return unless pair
+        return unless whole_line_owner?(pair)
+
+        Range.new(start_line: pair.start_line, end_line: pair.end_line)
+      end
+
+      private
+
+      def pair_for(path)
+        current = @analysis.root_object
+        pair = nil
+        segments = pointer_segments(path)
+        until segments.empty?
+          segment = segments.shift
+          pair = pair_with_key(current, segment)
+          return unless pair
+
+          current = pair.value_node
+        end
+        pair
+      end
+
+      def pair_with_key(object, key)
+        return unless object&.object?
+
+        object.pairs.find { |candidate| candidate.key_name == key }
+      end
+
+      def pointer_segments(path)
+        return [] if path.to_s.empty?
+
+        path.to_s.split('/').drop(1).map do |segment|
+          segment.gsub('~1', '/').gsub('~0', '~')
+        end
+      end
+
+      def whole_line_owner?(pair)
+        start_line = pair.start_line
+        end_line = pair.end_line
+        return false unless start_line && end_line
+        return false unless @lines.fetch(end_line - 1, '').end_with?("\n")
+
+        start_column = pair.node.start_point.fetch(:column)
+        @lines.fetch(start_line - 1, '').slice(0, start_column).to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/json/merge/three_way_decision.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Computes base-aware JSON-family semantic decisions without rendering.
+    # rubocop:disable Metrics/ClassLength -- recursive decisions and classifications form one algorithm
+    class ThreeWayDecision
+      State = Data.define(:present, :value) do
+        def self.present(value)
+          new(present: true, value: value)
+        end
+
+        def self.missing
+          @missing ||= new(present: false, value: nil)
+        end
+
+        def to_h
+          present ? { present: true, value: value } : { present: false }
+        end
+      end
+
+      Result = Data.define(:state, :conflicts, :changes) do
+        def present?
+          state.present
+        end
+
+        def value
+          state.value
+        end
+
+        def conflicted?
+          !conflicts.empty?
+        end
+      end
+
+      def call(base:, ours:, theirs:)
+        merge_states(
+          State.present(base),
+          State.present(ours),
+          State.present(theirs),
+          path: ''
+        )
+      end
+
+      private
+
+      def merge_states(base, ours, theirs, path:)
+        return success(ours) if ours == theirs
+        return success(theirs, change: classify(path, base, ours, theirs)) if base == ours
+        return success(ours, change: classify(path, base, ours, theirs)) if base == theirs
+        return merge_added_objects(ours, theirs, path: path) if added_object_states?(base, ours, theirs)
+        return merge_objects(base, ours, theirs, path: path) if object_states?(base, ours, theirs)
+
+        conflict(base, ours, theirs, path: path)
+      end
+
+      def merge_objects(base, ours, theirs, path:)
+        aggregate = { value: {}, conflicts: [], changes: [] }
+        states = [base, ours, theirs]
+        ordered_keys(base.value, ours.value, theirs.value).each do |key|
+          merge_object_key(aggregate, key, states, path: path)
+        end
+
+        Result.new(
+          state: State.present(aggregate[:value]),
+          conflicts: aggregate[:conflicts].freeze,
+          changes: aggregate[:changes].freeze
+        )
+      end
+
+      def merge_added_objects(ours, theirs, path:)
+        merge_objects(State.present({}), ours, theirs, path: path)
+      end
+
+      def merge_object_key(aggregate, key, states, path:)
+        child_states = states.map { |state| state_for(state.value, key) }
+        child = merge_states(*child_states, path: child_path(path, key))
+        aggregate[:value][key] = child.value if child.present?
+        aggregate[:conflicts].concat(child.conflicts)
+        aggregate[:changes].concat(child.changes)
+      end
+
+      def success(state, change: nil)
+        Result.new(
+          state: state,
+          conflicts: [].freeze,
+          changes: change ? [change].freeze : [].freeze
+        )
+      end
+
+      def conflict(base, ours, theirs, path:)
+        classification = classify(path, base, ours, theirs)
+        selected = ours.present ? ours : theirs
+        Result.new(
+          state: selected,
+          conflicts: [conflict_payload(base, ours, theirs, path, classification)].freeze,
+          changes: [classification].freeze
+        )
+      end
+
+      def conflict_payload(base, ours, theirs, path, classification)
+        {
+          conflict_id: conflict_id(path),
+          category: conflict_category(ours, theirs),
+          path: path,
+          base: base.to_h,
+          ours: ours.to_h,
+          theirs: theirs.to_h,
+          change_classification: classification
+        }.freeze
+      end
+
+      def classify(path, base, ours, theirs)
+        {
+          path: path,
+          ours: change_state(base, ours),
+          theirs: change_state(base, theirs)
+        }.freeze
+      end
+
+      def change_state(base, side)
+        return :unchanged if base == side
+        return :added unless base.present
+        return :deleted unless side.present
+
+        :edited
+      end
+
+      def conflict_category(ours, theirs)
+        ours.present && theirs.present ? :edit_edit : :delete_edit
+      end
+
+      def object_states?(*states)
+        states.all? { |state| state.present && state.value.is_a?(Hash) }
+      end
+
+      def added_object_states?(base, ours, theirs)
+        !base.present &&
+          ours.present && ours.value.is_a?(Hash) &&
+          theirs.present && theirs.value.is_a?(Hash)
+      end
+
+      def state_for(object, key)
+        object.key?(key) ? State.present(object.fetch(key)) : State.missing
+      end
+
+      def ordered_keys(*objects)
+        objects.each_with_object([]) do |object, keys|
+          object.each_key { |key| keys << key unless keys.include?(key) }
+        end
+      end
+
+      def child_path(path, key)
+        "#{path}/#{escape_path_segment(key)}"
+      end
+
+      def escape_path_segment(key)
+        key.to_s.gsub('~', '~0').gsub('/', '~1')
+      end
+
+      def conflict_id(path)
+        suffix = path.delete_prefix('/').gsub(/[^a-zA-Z0-9_-]+/, '-')
+        "json-conflict-#{suffix.empty? ? 'root' : suffix}"
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/json/merge/version.rb

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

@@ -38,6 +38,9 @@ module Json
     autoload :ConflictResolver, 'json/merge/conflict_resolver'
     autoload :SmartMerger, 'json/merge/smart_merger'
     autoload :ObjectMatchRefiner, 'json/merge/object_match_refiner'
+    autoload :Provider, 'json/merge/provider'
+    autoload :SourceLocator, 'json/merge/source_locator'
+    autoload :ThreeWayDecision, 'json/merge/three_way_decision'
 
     class << self
       def register_backend!
@@ -67,6 +70,14 @@ module Json
       }
     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_json_backends
       json_backend_available_for_analysis?(TREE_SITTER_BACKEND.id) ? [TREE_SITTER_BACKEND] : []
     end
@@ -510,6 +521,7 @@ module Json
 end
 
 Json::Merge.register_backend!
+Json::Merge.register_provider!
 
 if defined?(Ast::Merge::RSpec::MergeGemRegistry)
   Ast::Merge::RSpec::MergeGemRegistry.register(

data/sig/json/merge.rbs

@@ -1,5 +1,51 @@
 module Json
   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
+
+    class SourceLocator
+      class Range < Data
+        attr_reader start_line: Integer
+        attr_reader end_line: Integer
+      end
+
+      def initialize: (String source, dialect: Symbol, ?backend: String | Symbol?) -> void
+      def pair_range: (String path) -> Range?
+    end
+
+    def self.merge_provider: () -> Provider
+    def self.register_provider!: (?replace: bool) -> Ast::Merge::_MergeProvider
+
+    class ThreeWayDecision
+      class State < Data
+        attr_reader present: bool
+        attr_reader value: untyped
+
+        def self.present: (untyped value) -> State
+        def self.missing: () -> State
+        def to_h: () -> Hash[Symbol, untyped]
+      end
+
+      class Result < Data
+        attr_reader state: State
+        attr_reader conflicts: Array[Hash[Symbol, untyped]]
+        attr_reader changes: Array[Hash[Symbol, untyped]]
+
+        def present?: () -> bool
+        def value: () -> untyped
+        def conflicted?: () -> bool
+      end
+
+      def call: (base: untyped, ours: untyped, theirs: untyped) -> Result
+    end
+
     module Version
       VERSION: String
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json-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,10 @@ files:
 - lib/json/merge/merge_result.rb
 - lib/json/merge/node_wrapper.rb
 - lib/json/merge/object_match_refiner.rb
+- lib/json/merge/provider.rb
 - lib/json/merge/smart_merger.rb
+- lib/json/merge/source_locator.rb
+- lib/json/merge/three_way_decision.rb
 - lib/json/merge/version.rb
 - sig/json/merge.rbs
 homepage: https://github.com/structuredmerge/structuredmerge-ruby
@@ -317,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/json-merge/7.1.1
+  documentation_uri: https://www.rubydoc.info/gems/json-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/json-merge