jsonc-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/jsonc/merge/comment_tracker.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Extracts and tracks comments with their line numbers from JSONC source.
+    # JSONC supports both single-line (//) and multi-line (/* */) comments.
+    #
+    # @example Basic usage
+    #   tracker = CommentTracker.new(jsonc_source)
+    #   tracker.comments # => [{line: 1, indent: 0, text: "This is a comment"}]
+    #   tracker.comment_at(1) # => {line: 1, indent: 0, text: "This is a comment"}
+    #
+    # @example Comment types
+    #   // Single-line comment
+    #   /* Block comment */
+    #   "key": "value" // Inline comment
+    class CommentTracker
+      # Regex to match full-line single-line comments
+      SINGLE_LINE_COMMENT_REGEX = %r{\A(\s*)//\s?(.*)\z}
+
+      # Regex to match full-line block comments (single line)
+      BLOCK_COMMENT_SINGLE_REGEX = %r{\A(\s*)/\*\s?(.*?)\s?\*/\s*\z}
+
+      # Regex to match inline single-line comments
+      INLINE_COMMENT_REGEX = %r{\s+//\s?(.*)$}
+
+      # @return [Array<Hash>] All extracted comments with metadata
+      attr_reader :comments
+
+      # @return [Array<String>] Source lines
+      attr_reader :lines
+
+      # Initialize comment tracker by scanning the source
+      #
+      # @param source [String] JSONC source code
+      def initialize(source)
+        @source = source
+        @lines = source.lines.map(&:chomp)
+        @comments = extract_comments
+        @comments_by_line = @comments.group_by { |c| c[:line] }
+      end
+
+      # Get comment at a specific line
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Hash, nil] Comment info or nil
+      def comment_at(line_num)
+        @comments_by_line[line_num]&.first
+      end
+
+      # Get all comments in a line range
+      #
+      # @param range [Range] Range of 1-based line numbers
+      # @return [Array<Hash>] Comments in the range
+      def comments_in_range(range)
+        @comments.select { |c| range.cover?(c[:line]) }
+      end
+
+      # Get leading comments before a line (consecutive comment lines immediately above)
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Array<Hash>] Leading comments
+      def leading_comments_before(line_num)
+        leading = []
+        current = line_num - 1
+
+        while current >= 1
+          comment = comment_at(current)
+          break unless comment && comment[:full_line]
+
+          leading.unshift(comment)
+          current -= 1
+        end
+
+        leading
+      end
+
+      # Get trailing comment on the same line (inline comment)
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Hash, nil] Inline comment or nil
+      def inline_comment_at(line_num)
+        comment = comment_at(line_num)
+        comment if comment && !comment[:full_line]
+      end
+
+      # Check if a line is a full-line comment
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def full_line_comment?(line_num)
+        comment = comment_at(line_num)
+        comment&.dig(:full_line) || false
+      end
+
+      # Check if a line is blank
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def blank_line?(line_num)
+        return false if line_num < 1 || line_num > @lines.length
+
+        @lines[line_num - 1].strip.empty?
+      end
+
+      private
+
+      def extract_comments
+        comments = []
+        in_block_comment = false
+        block_comment_indent = 0
+
+        @lines.each_with_index do |line, idx|
+          line_num = idx + 1
+
+          # Handle multi-line block comments
+          if in_block_comment
+            if line.include?("*/")
+              in_block_comment = false
+              # Multi-line block comment ends - we already captured the start
+            end
+            next
+          end
+
+          # Check for block comment start
+          if line.include?("/*") && !line.include?("*/")
+            in_block_comment = true
+            match = line.match(/\A(\s*)/)
+            block_comment_indent = match ? match[1].length : 0
+            comments << {
+              line: line_num,
+              indent: block_comment_indent,
+              text: line.sub(/\A\s*\/\*\s?/, "").strip,
+              full_line: true,
+              block: true,
+              raw: line,
+            }
+            next
+          end
+
+          # Check for single-line block comment
+          if (match = line.match(BLOCK_COMMENT_SINGLE_REGEX))
+            comments << {
+              line: line_num,
+              indent: match[1].length,
+              text: match[2],
+              full_line: true,
+              block: true,
+              raw: line,
+            }
+            next
+          end
+
+          # Check for full-line single-line comment
+          if (match = line.match(SINGLE_LINE_COMMENT_REGEX))
+            comments << {
+              line: line_num,
+              indent: match[1].length,
+              text: match[2],
+              full_line: true,
+              block: false,
+              raw: line,
+            }
+            next
+          end
+
+          # Check for inline comment (after JSON content)
+          # Be careful not to match // inside strings
+          if line.include?("//")
+            # Simple heuristic: if there's content before //, it might be inline
+            # This doesn't handle all edge cases with strings containing //
+            parts = line.split("//", 2)
+            if parts.length == 2 && !parts[0].strip.empty?
+              # Verify it's not inside a string by checking quote balance
+              before_comment = parts[0]
+              quote_count = before_comment.count('"') - before_comment.scan('\\"').count
+              if quote_count.even?
+                comments << {
+                  line: line_num,
+                  indent: 0,
+                  text: parts[1].strip,
+                  full_line: false,
+                  block: false,
+                  raw: "// #{parts[1].strip}",
+                }
+              end
+            end
+          end
+        end
+
+        comments
+      end
+    end
+  end
+end

data/lib/jsonc/merge/conflict_resolver.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Resolves conflicts between template and destination JSON content
+    # using structural signatures and configurable preferences.
+    #
+    # Inherits from Ast::Merge::ConflictResolverBase using the :batch strategy,
+    # which resolves all conflicts at once using signature maps.
+    #
+    # @example Basic usage
+    #   resolver = ConflictResolver.new(template_analysis, dest_analysis)
+    #   resolver.resolve(result)
+    #
+    # @see Ast::Merge::ConflictResolverBase
+    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, Hash] 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
+      # @param node_typing [Hash{Symbol,String => #call}, nil] Node typing configuration
+      #   for per-node-type preferences
+      def initialize(template_analysis, dest_analysis, preference: :destination, add_template_only_nodes: false, match_refiner: nil, node_typing: 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
+        )
+        @node_typing = node_typing
+        @emitter = Emitter.new
+      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
+
+          # Clear emitter for fresh merge
+          @emitter.clear
+
+          # Merge root-level statements via emitter
+          merge_node_lists_to_emitter(
+            template_statements,
+            dest_statements,
+            @template_analysis,
+            @dest_analysis,
+          )
+
+          # Transfer emitter output to result
+          # For now, add as single content block - we'll improve decision tracking later
+          emitted_content = @emitter.to_s
+          unless emitted_content.empty?
+            emitted_content.lines.each do |line|
+              result.add_line(line.chomp, decision: MergeResult::DECISION_MERGED, source: :merged)
+            end
+          end
+
+          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, emitting to emitter
+      # @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
+      def merge_node_lists_to_emitter(template_nodes, dest_nodes, template_analysis, dest_analysis)
+        # 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)
+            emit_freeze_block(dest_node)
+            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_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
+
+            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_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
+
+            processed_dest_sigs << dest_sig if dest_sig
+            processed_template_sigs << template_sig if template_sig
+          else
+            # Destination-only node - always keep
+            emit_node(dest_node, 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
+          emit_node(template_node, template_analysis)
+          processed_template_sigs << template_sig if template_sig
+        end
+      end
+
+      # Keep old merge_node_lists for now (will be removed later)
+      # This allows gradual migration
+
+      # Merge two matched nodes - for containers, recursively merge children
+      # Emits to emitter instead of result
+      # @param template_node [NodeWrapper] Template node
+      # @param dest_node [NodeWrapper] Destination node
+      # @param template_analysis [FileAnalysis] Template analysis
+      # @param dest_analysis [FileAnalysis] Destination analysis
+      def merge_matched_nodes_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
+        if dest_node.container? && template_node.container?
+          # Both are containers - recursively merge their children
+          merge_container_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
+        elsif dest_node.pair? && template_node.pair?
+          # Both are pairs - check if their values are OBJECTS (not arrays) that need recursive merge
+          template_value = template_node.value_node
+          dest_value = dest_node.value_node
+
+          # Only recursively merge if BOTH values are objects (not arrays)
+          # Arrays are replaced atomically based on preference
+          if template_value&.type == :object && dest_value&.type == :object &&
+              template_value.container? && dest_value.container?
+            # Both values are objects - recursively merge
+            @emitter.emit_nested_object_start(dest_node.key_name)
+
+            # Recursively merge the value objects
+            merge_node_lists_to_emitter(
+              template_value.mergeable_children,
+              dest_value.mergeable_children,
+              template_analysis,
+              dest_analysis,
+            )
+
+            # Emit closing brace
+            @emitter.emit_nested_object_end
+          elsif preference_for_pair(template_node, dest_node) == :destination
+            # Values are not both objects, or one/both are arrays - use preference and emit
+            # Arrays are always replaced, not merged
+            emit_node(dest_node, dest_analysis)
+          else
+            emit_node(template_node, template_analysis)
+          end
+        elsif preference_for_pair(template_node, dest_node) == :destination
+          # Leaf nodes or mismatched types - use preference
+          emit_node(dest_node, dest_analysis)
+        else
+          emit_node(template_node, template_analysis)
+        end
+      end
+
+      # Merge container nodes by emitting via emitter
+      # @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
+      def merge_container_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
+        # Emit opening bracket
+        if dest_node.object?
+          @emitter.emit_object_start
+        elsif dest_node.array?
+          @emitter.emit_array_start
+        end
+
+        # Recursively merge the children
+        template_children = template_node.mergeable_children
+        dest_children = dest_node.mergeable_children
+
+        merge_node_lists_to_emitter(
+          template_children,
+          dest_children,
+          template_analysis,
+          dest_analysis,
+        )
+
+        # Emit closing bracket
+        if dest_node.object?
+          @emitter.emit_object_end
+        elsif dest_node.array?
+          @emitter.emit_array_end
+        end
+      end
+
+      def preference_for_pair(template_node, dest_node)
+        return @preference unless @preference.is_a?(Hash)
+
+        typed_template = apply_node_typing(template_node)
+        typed_dest = apply_node_typing(dest_node)
+
+        if Ast::Merge::NodeTyping.typed_node?(typed_template)
+          merge_type = Ast::Merge::NodeTyping.merge_type_for(typed_template)
+          return @preference.fetch(merge_type) { default_preference } if merge_type
+        end
+
+        if Ast::Merge::NodeTyping.typed_node?(typed_dest)
+          merge_type = Ast::Merge::NodeTyping.merge_type_for(typed_dest)
+          return @preference.fetch(merge_type) { default_preference } if merge_type
+        end
+
+        default_preference
+      end
+
+      def apply_node_typing(node)
+        return node unless @node_typing
+        return node unless node
+
+        Ast::Merge::NodeTyping.process(node, @node_typing)
+      end
+
+      # Emit a single node to the emitter
+      # @param node [NodeWrapper] Node to emit
+      # @param analysis [FileAnalysis] Analysis for accessing source
+      def emit_node(node, analysis)
+        return if freeze_node?(node) # Freeze nodes handled separately
+
+        # Emit leading comments
+        if node.start_line
+          leading = analysis.comment_tracker.leading_comments_before(node.start_line)
+          leading.each do |comment|
+            @emitter.emit_tracked_comment(comment)
+          end
+        end
+
+        # Emit the node content
+        if node.pair?
+          # Emit as pair
+          key = node.key_name
+          value_node = node.value_node
+
+          if value_node
+            # Check if value is an object (not array) and needs recursive emission
+            if value_node.type == :object && value_node.container?
+              # Object value - emit structure recursively
+              @emitter.emit_nested_object_start(key)
+              # Recursively emit object children
+              value_node.mergeable_children.each do |child|
+                emit_node(child, analysis)
+              end
+              @emitter.emit_nested_object_end
+            else
+              # Leaf value or array - get its text and emit as simple pair
+              # Arrays are emitted as raw text (not recursively) because Emitter doesn't have emit_array_start(key)
+              value_text = if value_node.start_line == value_node.end_line
+                value_node.text
+              else
+                # Multi-line value - get all lines
+                lines = []
+                (value_node.start_line..value_node.end_line).each do |ln|
+                  lines << analysis.line_at(ln)
+                end
+                lines.join("\n")
+              end
+
+              @emitter.emit_pair(key, value_text) if key && value_text
+            end
+          end
+        elsif node.start_line && node.end_line
+          # Emit raw content for non-pair nodes
+          if node.start_line == node.end_line
+            # Single line - add directly
+            @emitter.lines << node.text
+          else
+            # Multi-line - collect and emit
+            lines = []
+            (node.start_line..node.end_line).each do |ln|
+              line = analysis.line_at(ln)
+              lines << line if line
+            end
+            @emitter.emit_raw_lines(lines)
+          end
+        end
+      end
+
+      # Emit a freeze block
+      # @param freeze_node [FreezeNode] Freeze block to emit
+      def emit_freeze_block(freeze_node)
+        @emitter.emit_raw_lines(freeze_node.lines)
+      end
+
+      # Build a map of refined matches using match_refiner
+      # @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 for refined matches
+      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_template = template_nodes.reject do |node|
+          sig = @template_analysis.generate_signature(node)
+          sig && matched_sigs.include?(sig)
+        end
+
+        unmatched_dest = dest_nodes.reject do |node|
+          sig = @dest_analysis.generate_signature(node)
+          sig && matched_sigs.include?(sig)
+        end
+
+        return {} if unmatched_template.empty? || unmatched_dest.empty?
+
+        # Call the match refiner
+        matches = @match_refiner.call(unmatched_template, unmatched_dest, {
+          template_analysis: @template_analysis,
+          dest_analysis: @dest_analysis,
+        })
+
+        # Build result map: template node -> dest node
+        matches.each_with_object({}) do |match, hash|
+          hash[match.template_node] = match.dest_node
+        end
+      end
+    end
+  end
+end