json-merge 1.0.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/json/merge/conflict_resolver.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Resolves conflicts between template and destination JSON content
+    # using structural signatures and configurable preferences.
+    #
+    # @example Basic usage
+    #   resolver = ConflictResolver.new(template_analysis, dest_analysis)
+    #   resolver.resolve(result)
+    class ConflictResolver < ::Ast::Merge::ConflictResolverBase
+      # Creates a new ConflictResolver
+      #
+      # @param template_analysis [FileAnalysis] Analyzed template file
+      # @param dest_analysis [FileAnalysis] Analyzed destination file
+      # @param preference [Symbol] Which version to prefer when
+      #   nodes have matching signatures:
+      #   - :destination (default) - Keep destination version (customizations)
+      #   - :template - Use template version (updates)
+      # @param add_template_only_nodes [Boolean] Whether to add nodes only in template
+      # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(template_analysis, dest_analysis, preference: :destination, add_template_only_nodes: false, match_refiner: nil, **options)
+        super(
+          strategy: :batch,
+          preference: preference,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+          add_template_only_nodes: add_template_only_nodes,
+          match_refiner: match_refiner,
+          **options
+        )
+      end
+
+      protected
+
+      # Resolve conflicts and populate the result using tree-based merging
+      #
+      # @param result [MergeResult] Result object to populate
+      def resolve_batch(result)
+        DebugLogger.time("ConflictResolver#resolve") do
+          template_statements = @template_analysis.statements
+          dest_statements = @dest_analysis.statements
+
+          # Merge root-level statements (typically just the root object)
+          merge_node_lists(
+            template_statements,
+            dest_statements,
+            @template_analysis,
+            @dest_analysis,
+            result,
+          )
+
+          DebugLogger.debug("Conflict resolution complete", {
+            template_statements: template_statements.size,
+            dest_statements: dest_statements.size,
+            result_lines: result.line_count,
+          })
+        end
+      end
+
+      private
+
+      # Recursively merge two lists of nodes (tree-based merge)
+      # @param template_nodes [Array<NodeWrapper>] Template nodes
+      # @param dest_nodes [Array<NodeWrapper>] Destination nodes
+      # @param template_analysis [FileAnalysis] Template analysis for line access
+      # @param dest_analysis [FileAnalysis] Destination analysis for line access
+      # @param result [MergeResult] Result to populate
+      def merge_node_lists(template_nodes, dest_nodes, template_analysis, dest_analysis, result)
+        # Build signature maps for matching
+        template_by_sig = build_signature_map(template_nodes, template_analysis)
+        dest_by_sig = build_signature_map(dest_nodes, dest_analysis)
+
+        # Build refined matches for nodes that don't match by signature
+        refined_matches = build_refined_matches(template_nodes, dest_nodes, template_by_sig, dest_by_sig)
+        refined_dest_to_template = refined_matches.invert
+
+        # Track which nodes have been processed
+        processed_template_sigs = ::Set.new
+        processed_dest_sigs = ::Set.new
+
+        # First pass: Process destination nodes
+        dest_nodes.each do |dest_node|
+          dest_sig = dest_analysis.generate_signature(dest_node)
+
+          # Freeze blocks from destination are always preserved
+          if freeze_node?(dest_node)
+            add_node_to_result(dest_node, result, :destination, MergeResult::DECISION_FREEZE_BLOCK, dest_analysis)
+            processed_dest_sigs << dest_sig if dest_sig
+            next
+          end
+
+          # Check for signature match
+          if dest_sig && template_by_sig[dest_sig]
+            template_info = template_by_sig[dest_sig].first
+            template_node = template_info[:node]
+
+            # Both have this node - merge them (recursively if containers)
+            merge_matched_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
+
+            processed_dest_sigs << dest_sig
+            processed_template_sigs << dest_sig
+          elsif refined_dest_to_template.key?(dest_node)
+            # Found refined match
+            template_node = refined_dest_to_template[dest_node]
+            template_sig = template_analysis.generate_signature(template_node)
+
+            # Merge matched nodes
+            merge_matched_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
+
+            processed_dest_sigs << dest_sig if dest_sig
+            processed_template_sigs << template_sig if template_sig
+          else
+            # Destination-only node - always keep
+            add_node_to_result(dest_node, result, :destination, MergeResult::DECISION_KEPT_DEST, dest_analysis)
+            processed_dest_sigs << dest_sig if dest_sig
+          end
+        end
+
+        # Second pass: Add template-only nodes if configured
+        return unless @add_template_only_nodes
+
+        template_nodes.each do |template_node|
+          template_sig = template_analysis.generate_signature(template_node)
+
+          # Skip if already processed
+          next if template_sig && processed_template_sigs.include?(template_sig)
+
+          # Skip freeze blocks from template
+          next if freeze_node?(template_node)
+
+          # Add template-only node
+          add_node_to_result(template_node, result, :template, MergeResult::DECISION_ADDED, template_analysis)
+          processed_template_sigs << template_sig if template_sig
+        end
+      end
+
+      # Merge two matched nodes - for containers, recursively merge children
+      # @param template_node [NodeWrapper] Template node
+      # @param dest_node [NodeWrapper] Destination node
+      # @param template_analysis [FileAnalysis] Template analysis
+      # @param dest_analysis [FileAnalysis] Destination analysis
+      # @param result [MergeResult] Result to populate
+      def merge_matched_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
+        if dest_node.container? && template_node.container?
+          # Both are containers - recursively merge their children
+          merge_container_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
+        elsif @preference == :destination
+          # Leaf nodes or mismatched types - use preference
+          add_node_to_result(dest_node, result, :destination, MergeResult::DECISION_KEPT_DEST, dest_analysis)
+        else
+          add_node_to_result(template_node, result, :template, MergeResult::DECISION_KEPT_TEMPLATE, template_analysis)
+        end
+      end
+
+      # Build a map of refined matches from template node to destination node.
+      # Uses the match_refiner to find additional pairings for nodes that didn't match by signature.
+      # @param template_nodes [Array<NodeWrapper>] Template nodes
+      # @param dest_nodes [Array<NodeWrapper>] Destination nodes
+      # @param template_by_sig [Hash] Template signature map
+      # @param dest_by_sig [Hash] Destination signature map
+      # @return [Hash] Map of template_node => dest_node
+      def build_refined_matches(template_nodes, dest_nodes, template_by_sig, dest_by_sig)
+        return {} unless @match_refiner
+
+        # Find unmatched nodes
+        matched_sigs = template_by_sig.keys & dest_by_sig.keys
+        unmatched_t_nodes = template_nodes.reject do |n|
+          sig = @template_analysis.generate_signature(n)
+          sig && matched_sigs.include?(sig)
+        end
+        unmatched_d_nodes = dest_nodes.reject do |n|
+          sig = @dest_analysis.generate_signature(n)
+          sig && matched_sigs.include?(sig)
+        end
+
+        return {} if unmatched_t_nodes.empty? || unmatched_d_nodes.empty?
+
+        # Call the refiner
+        matches = @match_refiner.call(unmatched_t_nodes, unmatched_d_nodes, {
+          template_analysis: @template_analysis,
+          dest_analysis: @dest_analysis,
+        })
+
+        # Build result map: template node -> dest node
+        matches.each_with_object({}) do |match, h|
+          h[match.template_node] = match.dest_node
+        end
+      end
+
+      # Merge two container nodes by emitting opening, recursively merging children, then closing
+      # @param template_node [NodeWrapper] Template container node
+      # @param dest_node [NodeWrapper] Destination container node
+      # @param template_analysis [FileAnalysis] Template analysis
+      # @param dest_analysis [FileAnalysis] Destination analysis
+      # @param result [MergeResult] Result to populate
+      def merge_container_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
+        # Use destination's opening line (or template if dest doesn't have one)
+        opening = dest_node.opening_line || template_node.opening_line
+        result.add_line(opening, decision: MergeResult::DECISION_MERGED, source: :merged) if opening
+
+        # Recursively merge the children
+        template_children = template_node.mergeable_children
+        dest_children = dest_node.mergeable_children
+
+        merge_node_lists(
+          template_children,
+          dest_children,
+          template_analysis,
+          dest_analysis,
+          result,
+        )
+
+        # Use destination's closing line (or template if dest doesn't have one)
+        closing = dest_node.closing_line || template_node.closing_line
+        result.add_line(closing, decision: MergeResult::DECISION_MERGED, source: :merged) if closing
+      end
+
+      # Add a node to the result (non-container or leaf node)
+      # @param node [NodeWrapper] Node to add
+      # @param result [MergeResult] Result to populate
+      # @param source [Symbol] :template or :destination
+      # @param decision [String] Decision constant
+      # @param analysis [FileAnalysis] Analysis for line access
+      def add_node_to_result(node, result, source, decision, analysis)
+        if freeze_node?(node)
+          result.add_freeze_block(node)
+        elsif node.is_a?(NodeWrapper)
+          add_wrapper_to_result(node, result, source, decision, analysis)
+        else
+          DebugLogger.debug("Unknown node type", {node_type: node.class.name})
+        end
+      end
+
+      def add_wrapper_to_result(wrapper, result, source, decision, analysis)
+        return unless wrapper.start_line && wrapper.end_line
+
+        # Add the node content line by line
+        (wrapper.start_line..wrapper.end_line).each do |line_num|
+          line = analysis.line_at(line_num)
+          next unless line
+
+          result.add_line(line.chomp, decision: decision, source: source, original_line: line_num)
+        end
+      end
+    end
+  end
+end

data/lib/json/merge/debug_logger.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Debug logging utility for Json::Merge.
+    # Extends the base Ast::Merge::DebugLogger with Json-specific configuration.
+    #
+    # @example Enable debug logging
+    #   ENV['JSON_MERGE_DEBUG'] = '1'
+    #   DebugLogger.debug("Processing node", {type: "pair", line: 5})
+    #
+    # @example Disable debug logging (default)
+    #   DebugLogger.debug("This won't be printed", {})
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      # Json-specific configuration
+      self.env_var_name = "JSON_MERGE_DEBUG"
+      self.log_prefix = "[Json::Merge]"
+
+      class << self
+        # Override log_node to handle Json-specific node types.
+        #
+        # @param node [Object] Node to log information about
+        # @param label [String] Label for the node
+        def log_node(node, label: "Node")
+          return unless enabled?
+
+          info = case node
+          when Json::Merge::NodeWrapper
+            {type: node.type.to_s, lines: "#{node.start_line}..#{node.end_line}"}
+          else
+            extract_node_info(node)
+          end
+
+          debug(label, info)
+        end
+      end
+    end
+  end
+end

data/lib/json/merge/emitter.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Custom JSON emitter that preserves comments and formatting.
+    # This class provides utilities for emitting JSON while maintaining
+    # the original structure, comments, and style choices.
+    #
+    # @example Basic usage
+    #   emitter = Emitter.new
+    #   emitter.emit_object_start
+    #   emitter.emit_pair("key", '"value"')
+    #   emitter.emit_object_end
+    class Emitter
+      # @return [Array<String>] Output lines
+      attr_reader :lines
+
+      # @return [Integer] Current indentation level
+      attr_reader :indent_level
+
+      # @return [Integer] Spaces per indent level
+      attr_reader :indent_size
+
+      # Initialize a new emitter
+      #
+      # @param indent_size [Integer] Number of spaces per indent level
+      def initialize(indent_size: 2)
+        @lines = []
+        @indent_level = 0
+        @indent_size = indent_size
+        @needs_comma = false
+      end
+
+      # Emit a single-line comment
+      #
+      # @param text [String] Comment text (without //)
+      # @param inline [Boolean] Whether this is an inline comment
+      def emit_comment(text, inline: false)
+        if inline
+          # Inline comments are appended to the last line
+          return if @lines.empty?
+
+          @lines[-1] = "#{@lines[-1]} // #{text}"
+        else
+          @lines << "#{current_indent}// #{text}"
+        end
+      end
+
+      # Emit a block comment
+      #
+      # @param text [String] Comment text
+      def emit_block_comment(text)
+        @lines << "#{current_indent}/* #{text} */"
+      end
+
+      # Emit leading comments
+      #
+      # @param comments [Array<Hash>] Comment hashes from CommentTracker
+      def emit_leading_comments(comments)
+        comments.each do |comment|
+          indent = " " * (comment[:indent] || 0)
+          @lines << if comment[:block]
+            "#{indent}/* #{comment[:text]} */"
+          else
+            "#{indent}// #{comment[:text]}"
+          end
+        end
+      end
+
+      # Emit a blank line
+      def emit_blank_line
+        @lines << ""
+      end
+
+      # Emit object start
+      def emit_object_start
+        add_comma_if_needed
+        @lines << "#{current_indent}{"
+        @indent_level += 1
+        @needs_comma = false
+      end
+
+      # Emit object end
+      def emit_object_end
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}}"
+        @needs_comma = true
+      end
+
+      # Emit array start
+      #
+      # @param key [String, nil] Key name if this array is a value in an object
+      def emit_array_start(key = nil)
+        add_comma_if_needed
+        @lines << if key
+          "#{current_indent}\"#{key}\": ["
+        else
+          "#{current_indent}["
+        end
+        @indent_level += 1
+        @needs_comma = false
+      end
+
+      # Emit array end
+      def emit_array_end
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}]"
+        @needs_comma = true
+      end
+
+      # Emit a key-value pair
+      #
+      # @param key [String] Key name (without quotes)
+      # @param value [String] Value (already formatted, e.g., '"string"', '123', 'true')
+      # @param inline_comment [String, nil] Optional inline comment
+      def emit_pair(key, value, inline_comment: nil)
+        add_comma_if_needed
+        line = "#{current_indent}\"#{key}\": #{value}"
+        line += " // #{inline_comment}" if inline_comment
+        @lines << line
+        @needs_comma = true
+      end
+
+      # Emit an array element
+      #
+      # @param value [String] Value (already formatted)
+      # @param inline_comment [String, nil] Optional inline comment
+      def emit_array_element(value, inline_comment: nil)
+        add_comma_if_needed
+        line = "#{current_indent}#{value}"
+        line += " // #{inline_comment}" if inline_comment
+        @lines << line
+        @needs_comma = true
+      end
+
+      # Emit raw lines (for preserving existing content)
+      #
+      # @param raw_lines [Array<String>] Lines to emit as-is
+      def emit_raw_lines(raw_lines)
+        raw_lines.each { |line| @lines << line.chomp }
+      end
+
+      # Get the output as a single string
+      #
+      # @return [String]
+      def to_json
+        content = @lines.join("\n")
+        content += "\n" unless content.empty? || content.end_with?("\n")
+        content
+      end
+
+      # Alias for consistency
+      # @return [String]
+      alias_method :to_s, :to_json
+
+      # Clear the output
+      def clear
+        @lines = []
+        @indent_level = 0
+        @needs_comma = false
+      end
+
+      private
+
+      def current_indent
+        " " * (@indent_level * @indent_size)
+      end
+
+      def add_comma_if_needed
+        return unless @needs_comma && @lines.any?
+
+        # Add comma to the previous line if it doesn't already have one
+        last_line = @lines.last
+        return if last_line.strip.empty?
+        return if last_line.rstrip.end_with?(",")
+        return if last_line.rstrip.end_with?("{")
+        return if last_line.rstrip.end_with?("[")
+
+        @lines[-1] = "#{last_line},"
+      end
+    end
+  end
+end