json-merge 7.0.0 → 7.1.1

data/lib/json/merge/object_match_refiner.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Match refiner for JSON objects and array elements that didn't match by exact signature.
+    #
+    # This refiner uses fuzzy matching to pair JSON nodes that have:
+    # - Similar key names in objects (e.g., `databaseUrl` vs `database_url`)
+    # - Array elements with similar structure or content
+    # - Objects with overlapping keys but different values
+    #
+    # The matching algorithm considers:
+    # - Key name similarity for object pairs (Levenshtein distance)
+    # - Value type and content similarity
+    # - Structural overlap for nested objects
+    #
+    # @example Basic usage
+    #   refiner = ObjectMatchRefiner.new(threshold: 0.6)
+    #   matches = refiner.call(template_nodes, dest_nodes)
+    #
+    # @example With custom weights
+    #   refiner = ObjectMatchRefiner.new(
+    #     threshold: 0.5,
+    #     key_weight: 0.6,
+    #     value_weight: 0.4
+    #   )
+    #
+    # @see Ast::Merge::MatchRefinerBase
+    class ObjectMatchRefiner < Ast::Merge::MatchRefinerBase
+      # Default weight for key similarity
+      DEFAULT_KEY_WEIGHT = 0.7
+
+      # Default weight for value similarity
+      DEFAULT_VALUE_WEIGHT = 0.3
+
+      # @return [Float] Weight for key similarity (0.0-1.0)
+      attr_reader :key_weight
+
+      # @return [Float] Weight for value similarity (0.0-1.0)
+      attr_reader :value_weight
+
+      # Initialize an object match refiner.
+      #
+      # @param threshold [Float] Minimum score to accept a match (default: 0.5)
+      # @param key_weight [Float] Weight for key similarity (default: 0.7)
+      # @param value_weight [Float] Weight for value similarity (default: 0.3)
+      def initialize(threshold: DEFAULT_THRESHOLD, key_weight: DEFAULT_KEY_WEIGHT, value_weight: DEFAULT_VALUE_WEIGHT,
+                     **options)
+        super(threshold: threshold, **options)
+        @key_weight = key_weight
+        @value_weight = value_weight
+      end
+
+      # Find matches between unmatched JSON nodes.
+      #
+      # Handles both object key-value pairs and array elements.
+      #
+      # @param template_nodes [Array] Unmatched nodes from template
+      # @param dest_nodes [Array] Unmatched nodes from destination
+      # @param context [Hash] Additional context
+      # @return [Array<MatchResult>] Array of node matches
+      def call(template_nodes, dest_nodes, _context = {})
+        # Match object pairs (key-value entries)
+        pair_matches = match_pairs(template_nodes, dest_nodes)
+
+        # Match array elements (objects within arrays)
+        array_matches = match_array_objects(template_nodes, dest_nodes)
+
+        pair_matches + array_matches
+      end
+
+      private
+
+      # Match key-value pairs from JSON objects.
+      #
+      # @param template_nodes [Array] Template nodes
+      # @param dest_nodes [Array] Destination nodes
+      # @return [Array<MatchResult>]
+      def match_pairs(template_nodes, dest_nodes)
+        template_pairs = template_nodes.select { |n| pair_node?(n) }
+        dest_pairs = dest_nodes.select { |n| pair_node?(n) }
+
+        return [] if template_pairs.empty? || dest_pairs.empty?
+
+        greedy_match(template_pairs, dest_pairs) do |t_node, d_node|
+          compute_pair_similarity(t_node, d_node)
+        end
+      end
+
+      # Match object elements from JSON arrays.
+      #
+      # @param template_nodes [Array] Template nodes
+      # @param dest_nodes [Array] Destination nodes
+      # @return [Array<MatchResult>]
+      def match_array_objects(template_nodes, dest_nodes)
+        template_objects = template_nodes.select { |n| object_node?(n) && !pair_node?(n) }
+        dest_objects = dest_nodes.select { |n| object_node?(n) && !pair_node?(n) }
+
+        return [] if template_objects.empty? || dest_objects.empty?
+
+        greedy_match(template_objects, dest_objects) do |t_node, d_node|
+          compute_object_similarity(t_node, d_node)
+        end
+      end
+
+      # Check if a node is a key-value pair.
+      #
+      # @param node [Object] Node to check
+      # @return [Boolean]
+      def pair_node?(node)
+        return false unless node.respond_to?(:pair?)
+
+        node.pair?
+      end
+
+      # Check if a node is a JSON object.
+      #
+      # @param node [Object] Node to check
+      # @return [Boolean]
+      def object_node?(node)
+        return false unless node.respond_to?(:object?)
+
+        node.object?
+      end
+
+      # Compute similarity score between two key-value pairs.
+      #
+      # @param t_pair [NodeWrapper] Template pair
+      # @param d_pair [NodeWrapper] Destination pair
+      # @return [Float] Similarity score (0.0-1.0)
+      def compute_pair_similarity(t_pair, d_pair)
+        t_key = t_pair.key_name
+        d_key = d_pair.key_name
+
+        return 0.0 unless t_key && d_key
+
+        key_score = key_similarity(t_key, d_key)
+        value_score = value_similarity(t_pair.value_node, d_pair.value_node)
+
+        (key_score * key_weight) + (value_score * value_weight)
+      end
+
+      # Compute similarity score between two JSON objects.
+      #
+      # @param t_obj [NodeWrapper] Template object
+      # @param d_obj [NodeWrapper] Destination object
+      # @return [Float] Similarity score (0.0-1.0)
+      def compute_object_similarity(t_obj, d_obj)
+        t_keys = extract_keys(t_obj)
+        d_keys = extract_keys(d_obj)
+
+        return 1.0 if t_keys.empty? && d_keys.empty?
+        return 0.0 if t_keys.empty? || d_keys.empty?
+
+        # Compute key overlap
+        common_keys = (t_keys & d_keys).size
+        total_keys = (t_keys | d_keys).size
+        key_overlap = common_keys.to_f / total_keys
+
+        # Compute fuzzy key similarity for non-exact matches
+        fuzzy_score = compute_fuzzy_key_matches(t_keys - d_keys, d_keys - t_keys)
+
+        # Combine exact overlap and fuzzy matching
+        (key_overlap * 0.7) + (fuzzy_score * 0.3)
+      end
+
+      # Compute fuzzy matches between two sets of keys.
+      #
+      # @param keys1 [Array<String>] First set of keys
+      # @param keys2 [Array<String>] Second set of keys
+      # @return [Float] Fuzzy match score (0.0-1.0)
+      def compute_fuzzy_key_matches(keys1, keys2)
+        return 1.0 if keys1.empty? && keys2.empty?
+        return 0.0 if keys1.empty? || keys2.empty?
+
+        total_similarity = 0.0
+        keys1.each do |k1|
+          best_match = keys2.map { |k2| key_similarity(k1, k2) }.max || 0.0
+          total_similarity += best_match
+        end
+
+        total_similarity / keys1.size
+      end
+
+      # Extract keys from a JSON object.
+      #
+      # @param obj [NodeWrapper] Object node
+      # @return [Array<String>] Keys
+      def extract_keys(obj)
+        return [] unless obj.respond_to?(:pairs)
+
+        obj.pairs.map(&:key_name).compact
+      end
+
+      # Compute similarity between two keys.
+      #
+      # @param key1 [String] First key
+      # @param key2 [String] Second key
+      # @return [Float] Key similarity (0.0-1.0)
+      def key_similarity(key1, key2)
+        return 1.0 if key1 == key2
+
+        str1 = normalize_key(key1.to_s)
+        str2 = normalize_key(key2.to_s)
+
+        string_similarity(str1, str2)
+      end
+
+      # Normalize a key for comparison.
+      # Converts to lowercase and normalizes common naming conventions.
+      #
+      # @param key [String] Key to normalize
+      # @return [String] Normalized key
+      def normalize_key(key)
+        # Convert camelCase to snake_case first, then normalize
+        key.gsub(/([A-Z])/) { "_#{::Regexp.last_match(1).downcase}" }
+           .downcase
+           .gsub(/[-_]/, '')
+      end
+
+      # Compute similarity between two values.
+      #
+      # @param t_value [NodeWrapper, nil] Template value
+      # @param d_value [NodeWrapper, nil] Destination value
+      # @return [Float] Value similarity (0.0-1.0)
+      def value_similarity(t_value, d_value)
+        return 0.5 unless t_value && d_value
+
+        # Check if they're the same type
+        return 0.0 unless same_value_type?(t_value, d_value)
+
+        if t_value.string?
+          # Compare string values
+          t_text = extract_string_value(t_value)
+          d_text = extract_string_value(d_value)
+          string_similarity(t_text, d_text)
+        elsif t_value.object?
+          # Compare object structures
+          compute_object_similarity(t_value, d_value)
+        elsif t_value.array?
+          # Compare array lengths
+          array_similarity(t_value, d_value)
+        else
+          # Same type, consider similar
+          0.5
+        end
+      end
+
+      # Check if two values have the same JSON type.
+      #
+      # @param val1 [NodeWrapper] First value
+      # @param val2 [NodeWrapper] Second value
+      # @return [Boolean]
+      def same_value_type?(val1, val2)
+        val1.type == val2.type
+      end
+
+      # Extract string content from a string node.
+      #
+      # @param node [NodeWrapper] String node
+      # @return [String]
+      def extract_string_value(node)
+        # String nodes include quotes, remove them
+        text = node.respond_to?(:text) ? node.text : ''
+        text.gsub(/\A"|"\z/, '')
+      end
+
+      # Compute similarity between two arrays.
+      #
+      # @param arr1 [NodeWrapper] First array
+      # @param arr2 [NodeWrapper] Second array
+      # @return [Float] Array similarity (0.0-1.0)
+      def array_similarity(arr1, arr2)
+        len1 = arr1.respond_to?(:elements) ? arr1.elements.size : 0
+        len2 = arr2.respond_to?(:elements) ? arr2.elements.size : 0
+
+        return 1.0 if len1.zero? && len2.zero?
+        return 0.0 if len1.zero? || len2.zero?
+
+        [len1, len2].min.to_f / [len1, len2].max
+      end
+
+      # Compute string similarity using Levenshtein distance.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @return [Float] Similarity score (0.0-1.0)
+      def string_similarity(str1, str2)
+        return 1.0 if str1 == str2
+        return 0.0 if str1.to_s.empty? || str2.to_s.empty?
+
+        distance = levenshtein_distance(str1.to_s, str2.to_s)
+        max_len = [str1.to_s.length, str2.to_s.length].max
+
+        1.0 - (distance.to_f / max_len)
+      end
+
+      # Compute Levenshtein distance between two strings.
+      #
+      # Uses Wagner-Fischer algorithm with O(min(m,n)) space.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @return [Integer] Edit distance
+      def levenshtein_distance(str1, str2)
+        return str2.length if str1.empty?
+        return str1.length if str2.empty?
+
+        # Ensure str1 is the shorter string for space optimization
+        str1, str2 = str2, str1 if str1.length > str2.length
+
+        m = str1.length
+        n = str2.length
+
+        # Use two rows instead of full matrix
+        prev_row = (0..m).to_a
+        curr_row = Array.new(m + 1, 0)
+
+        (1..n).each do |j|
+          curr_row[0] = j
+
+          (1..m).each do |i|
+            cost = str1[i - 1] == str2[j - 1] ? 0 : 1
+            curr_row[i] = [
+              prev_row[i] + 1,      # deletion
+              curr_row[i - 1] + 1,  # insertion
+              prev_row[i - 1] + cost # substitution
+            ].min
+          end
+
+          prev_row, curr_row = curr_row, prev_row
+        end
+
+        prev_row[m]
+      end
+    end
+  end
+end

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/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.1'
     end
-
-    VERSION = Version::VERSION
+    # Current gem version exposed at the traditional constant location.
+    VERSION = Version::VERSION # Traditional Constant Location
   end
 end