json-merge 7.0.0 → 7.1.3

data/lib/json/merge/smart_merger.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # High-level merger for JSON / JSONC content.
+    #
+    # @example Basic usage
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   result = merger.merge
+    #   File.write("merged.json", result.output)
+    #
+    # @example With options
+    #   merger = SmartMerger.new(template, dest,
+    #     preference: :template,
+    #     add_template_only_nodes: true)
+    #   result = merger.merge
+    #
+    # @example Enable fuzzy matching
+    #   merger = SmartMerger.new(template, dest, match_refiner: ObjectMatchRefiner.new)
+    #
+    # @example With regions (embedded content)
+    #   merger = SmartMerger.new(template, dest,
+    #     regions: [{ detector: SomeDetector.new, merger_class: SomeMerger }])
+    class SmartMerger < ::Ast::Merge::SmartMergerBase
+      include ::Ast::Merge::Runtime::RootSessionSupport
+
+      attr_reader :runtime_session, :corruption_handling, :dialect
+
+      # Creates a new SmartMerger
+      #
+      # @param template_content [String] Template JSON content
+      # @param dest_content [String] Destination JSON content
+      # @param signature_generator [Proc, nil] Custom signature generator
+      # @param preference [Symbol, Hash] :destination, :template, or per-type Hash
+      # @param add_template_only_nodes [Boolean] Whether to add nodes only found in template
+      # @param remove_template_missing_nodes [Boolean] Whether to remove nodes missing from template
+      # @param freeze_token [String, nil] Token for freeze block markers
+      # @param match_refiner [#call, nil] Match refiner for fuzzy matching
+      # @param regions [Array<Hash>, nil] Region configurations for nested merging
+      # @param region_placeholder [String, nil] Custom placeholder for regions
+      # @param node_typing [Hash{Symbol,String => #call}, nil] Node typing configuration
+      #   for per-node-type merge preferences
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(
+        template_content,
+        dest_content,
+        signature_generator: nil,
+        preference: :destination,
+        add_template_only_nodes: false,
+        remove_template_missing_nodes: false,
+        corruption_handling: :heal,
+        freeze_token: nil,
+        match_refiner: nil,
+        regions: nil,
+        region_placeholder: nil,
+        node_typing: nil,
+        merge_arrays: true,
+        preserve_atomic_formatting: false,
+        dialect: :jsonc,
+        **options
+      )
+        @remove_template_missing_nodes = remove_template_missing_nodes
+        @corruption_handling = ::Ast::Merge::Healer.normalize_mode(corruption_handling)
+        @merge_arrays = merge_arrays
+        @preserve_atomic_formatting = preserve_atomic_formatting
+        @dialect = dialect.to_sym
+        unless %i[json jsonc json5].include?(@dialect)
+          raise ArgumentError, "Unsupported JSON dialect #{dialect.inspect}. Expected json, jsonc, or json5."
+        end
+
+        super(
+          template_content,
+          dest_content,
+          signature_generator: signature_generator,
+          preference: preference,
+          add_template_only_nodes: add_template_only_nodes,
+          remove_template_missing_nodes: remove_template_missing_nodes,
+          freeze_token: freeze_token,
+          match_refiner: match_refiner,
+          regions: regions,
+          region_placeholder: region_placeholder,
+          node_typing: node_typing,
+          merge_arrays: merge_arrays,
+          preserve_atomic_formatting: preserve_atomic_formatting,
+          dialect: @dialect,
+          **options
+        )
+      end
+
+      # Backward-compatible options hash
+      #
+      # @return [Hash] The merge options
+      def options
+        {
+          preference: @preference,
+          add_template_only_nodes: @add_template_only_nodes,
+          remove_template_missing_nodes: @remove_template_missing_nodes,
+          resolution_mode: @resolution_mode,
+          unresolved_policy: @unresolved_policy.to_h,
+          corruption_handling: @corruption_handling,
+          match_refiner: @match_refiner,
+          dialect: @dialect
+        }
+      end
+
+      # Perform the merge operation and return the full MergeResult object.
+      #
+      # @return [MergeResult] The merge result containing merged JSON content and metadata
+      def merge_result
+        return @merge_result if @merge_result
+
+        root_operation = start_runtime_session!
+        @merge_result = super
+        complete_runtime_session!(root_operation, @merge_result)
+        @merge_result
+      rescue StandardError => e
+        fail_runtime_session!(root_operation, e)
+        raise
+      end
+
+      # Perform the merge and return detailed runtime-aware debug information.
+      #
+      # @return [Hash] Hash containing :content, :debug, :runtime, :statistics, and :decisions
+      def merge_with_debug
+        result_obj = merge_result
+        template_analysis_debug = {
+          valid: @template_analysis.valid?,
+          nodes: @template_analysis.nodes.size,
+          freeze_blocks: @template_analysis.freeze_blocks.size
+        }
+        dest_analysis_debug = {
+          valid: @dest_analysis.valid?,
+          nodes: @dest_analysis.nodes.size,
+          freeze_blocks: @dest_analysis.freeze_blocks.size
+        }
+
+        {
+          content: result_obj.to_json,
+          debug: {
+            template_nodes: template_analysis_debug[:nodes],
+            dest_nodes: dest_analysis_debug[:nodes],
+            preference: @preference,
+            add_template_only_nodes: @add_template_only_nodes,
+            remove_template_missing_nodes: @remove_template_missing_nodes,
+            corruption_handling: @corruption_handling,
+            freeze_token: @freeze_token,
+            runtime_operation_count: runtime_session&.operations&.size || 0,
+            runtime_diagnostic_count: runtime_session&.diagnostics&.size || 0
+          },
+          runtime: runtime_session&.to_h,
+          statistics: result_obj.statistics,
+          decisions: result_obj.decision_summary,
+          template_analysis: template_analysis_debug,
+          dest_analysis: dest_analysis_debug
+        }
+      end
+
+      protected
+
+      # @return [Class] The analysis class for JSON files
+      def analysis_class
+        FileAnalysis
+      end
+
+      # @return [String] The default freeze token (not used for JSON)
+      def default_freeze_token
+        'json-merge'
+      end
+
+      # @return [Class] The resolver class for JSON files
+      def resolver_class
+        ConflictResolver
+      end
+
+      # @return [Class] The result class for JSON files
+      def result_class
+        MergeResult
+      end
+
+      # Perform the JSON-specific merge
+      #
+      # @return [MergeResult] The merge result
+      def perform_merge
+        @resolver.resolve(@result)
+
+        DebugLogger.debug('Merge complete', {
+                            lines: @result.line_count,
+                            decisions: @result.statistics
+                          })
+
+        @result
+      end
+
+      # Build the resolver with JSON-specific signature
+      def build_resolver
+        ConflictResolver.new(
+          @template_analysis,
+          @dest_analysis,
+          preference: @preference,
+          add_template_only_nodes: @add_template_only_nodes,
+          remove_template_missing_nodes: @remove_template_missing_nodes,
+          resolution_mode: @resolution_mode,
+          corruption_handling: @corruption_handling,
+          match_refiner: @match_refiner,
+          node_typing: @node_typing,
+          merge_arrays: @merge_arrays,
+          preserve_atomic_formatting: @preserve_atomic_formatting
+        )
+      end
+
+      # Build the result (no-arg constructor for JSON)
+      def build_result
+        MergeResult.new
+      end
+
+      # @return [Class] The template parse error class for JSON
+      def template_parse_error_class
+        TemplateParseError
+      end
+
+      # @return [Class] The destination parse error class for JSON
+      def destination_parse_error_class
+        DestinationParseError
+      end
+
+      private
+
+      def start_runtime_session!
+        start_runtime_root_session!(
+          surface_kind: :json_document,
+          declared_language: :json,
+          effective_language: :json,
+          operation_id: 'json-document-root',
+          delegate_name: 'json-runtime',
+          policy_context: {
+            preference: @preference,
+            add_template_only_nodes: @add_template_only_nodes,
+            remove_template_missing_nodes: @remove_template_missing_nodes,
+            resolution_mode: @resolution_mode,
+            unresolved_policy: @unresolved_policy.to_h
+          },
+          metadata: { merger: self.class.name },
+          options: {
+            preference: @preference,
+            add_template_only_nodes: @add_template_only_nodes,
+            remove_template_missing_nodes: @remove_template_missing_nodes,
+            resolution_mode: @resolution_mode,
+            unresolved_policy: @unresolved_policy.to_h
+          },
+          language_chain: [:json],
+          delegate_metadata: { merger: self.class.name }
+        )
+      end
+
+      def complete_runtime_session!(root_operation, merge_result)
+        complete_runtime_root_session!(
+          root_operation: root_operation,
+          replacement_text: merge_result.to_json,
+          unresolved_cases: merge_result.unresolved_cases,
+          metadata: {
+            stats: merge_result.statistics,
+            decisions: merge_result.decision_summary
+          }
+        )
+      end
+
+      def fail_runtime_session!(root_operation, error)
+        fail_runtime_root_session!(
+          root_operation: root_operation,
+          error: error,
+          kind: :merge_failed
+        )
+      end
+    end
+  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

@@ -2,10 +2,12 @@
 
 module Json
   module Merge
+    # Version namespace for this gem.
     module Version
-      VERSION = "7.0.0"
+      # Current gem version.
+      VERSION = '7.1.3'
     end
-
-    VERSION = Version::VERSION
+    # Current gem version exposed at the traditional constant location.
+    VERSION = Version::VERSION # Traditional Constant Location
   end
 end