json-merge 7.0.0 → 7.1.3

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,227 @@
+# 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.
+    #
+    # Inherits common emitter functionality from Ast::Merge::EmitterBase.
+    #
+    # @example Basic usage
+    #   emitter = Emitter.new
+    #   emitter.emit_object_start
+    #   emitter.emit_pair("key", '"value"')
+    #   emitter.emit_object_end
+    class Emitter < Ast::Merge::EmitterBase
+      include Ast::Merge::EmitterLineMetadataSupport
+
+      # @return [Boolean] Whether next item needs a comma
+      attr_reader :needs_comma
+
+      # Initialize subclass-specific state (comma tracking for JSON)
+      def initialize_subclass_state(**_options)
+        @needs_comma = false
+        initialize_line_metadata_state
+      end
+
+      # Clear subclass-specific state
+      def clear_subclass_state
+        @needs_comma = false
+        clear_line_metadata_state
+      end
+
+      def emit_blank_line
+        append_line('')
+      end
+
+      # Emit a tracked comment from CommentTracker
+      # @param comment [Hash] Comment with :text, :indent, :block
+      def emit_tracked_comment(comment)
+        indent = ' ' * (comment[:indent] || 0)
+        append_line(if comment[:block]
+                      "#{indent}/* #{comment[:text]} */"
+                    else
+                      "#{indent}// #{comment[:text]}"
+                    end)
+      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
+          append_line("#{current_indent}// #{text}")
+        end
+      end
+
+      # Emit a block comment
+      #
+      # @param text [String] Comment text
+      def emit_block_comment(text)
+        append_line("#{current_indent}/* #{text} */")
+      end
+
+      # Emit object start
+      def emit_object_start(metadata: nil)
+        add_comma_if_needed
+        append_line("#{current_indent}{", metadata)
+        indent
+        @needs_comma = false
+      end
+
+      # Emit object end
+      def emit_object_end(metadata: nil)
+        dedent
+        append_line("#{current_indent}}", metadata)
+        @needs_comma = true
+      end
+
+      # Emit array start
+      #
+      # @param key [String, nil] Key name if this array is a value in an object
+      # @param inline_comment [String, nil] Optional inline comment for the opening line
+      def emit_array_start(key = nil, inline_comment: nil, metadata: nil)
+        add_comma_if_needed
+        line = if key
+                 "#{current_indent}\"#{key}\": ["
+               else
+                 "#{current_indent}["
+               end
+        line += " // #{inline_comment}" if inline_comment
+        append_line(line, metadata)
+        indent
+        @needs_comma = false
+      end
+
+      # Emit array end
+      def emit_array_end(metadata: nil)
+        dedent
+        append_line("#{current_indent}]", metadata)
+        @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, metadata: nil)
+        add_comma_if_needed
+        line = "#{current_indent}\"#{key}\": #{value}"
+        line += " // #{inline_comment}" if inline_comment
+        append_line(line, metadata)
+        @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, metadata: nil)
+        add_comma_if_needed
+        line = "#{current_indent}#{value}"
+        line += " // #{inline_comment}" if inline_comment
+        append_line(line, metadata)
+        @needs_comma = true
+      end
+
+      # Emit a key with opening brace for nested object
+      # @param key [String] Key name
+      # @param inline_comment [String, nil] Optional inline comment for the opening line
+      def emit_nested_object_start(key, inline_comment: nil, metadata: nil)
+        add_comma_if_needed
+        line = "#{current_indent}\"#{key}\": {"
+        line += " // #{inline_comment}" if inline_comment
+        append_line(line, metadata)
+        indent
+        @needs_comma = false
+      end
+
+      # Emit closing brace for nested object
+      def emit_nested_object_end(metadata: nil)
+        dedent
+        append_line("#{current_indent}}", metadata)
+        @needs_comma = true
+      end
+
+      def emit_raw_lines(raw_lines, metadata: nil)
+        raw_lines.each_with_index do |line, idx|
+          append_line(
+            line.chomp,
+            expanded_line_metadata(metadata, idx)
+          )
+        end
+      end
+
+      def emit_raw_fragment(fragment, metadata: nil)
+        add_comma_if_needed
+        fragment.to_s.lines(chomp: true).each_with_index do |line, idx|
+          append_line(
+            "#{current_indent}#{line}",
+            expanded_line_metadata(metadata, idx)
+          )
+        end
+        @needs_comma = true
+      end
+
+      # Get the output as a JSON string
+      #
+      # @return [String]
+      def to_json(*_args)
+        to_s
+      end
+
+      private
+
+      def add_comma_if_needed
+        return unless @needs_comma && @lines.any?
+
+        line_index = @lines.length - 1
+        while line_index >= 0
+          line = @lines[line_index]
+          stripped = line.strip
+          if stripped.empty? || comment_line?(stripped)
+            line_index -= 1
+            next
+          end
+
+          break
+        end
+
+        return if line_index.negative?
+
+        # Add comma to the previous structural line if it doesn't already have one
+        last_line = @lines[line_index]
+        @lines[line_index] = add_comma_to_line(last_line)
+      end
+
+      def comment_line?(stripped_line)
+        stripped_line.start_with?('//', '/*', '*', '*/')
+      end
+
+      def add_comma_to_line(line)
+        return line if line.strip.empty?
+
+        inline_match = line.match(%r{\A(?<content>.*?)(?<spacing>\s+)(?<comment>//.*)\z})
+        if inline_match
+          content = inline_match[:content].rstrip
+          return line if content.end_with?(',', '{', '[')
+
+          return "#{content}, #{inline_match[:comment]}"
+        end
+
+        stripped = line.rstrip
+        return line if stripped.end_with?(',', '{', '[')
+
+        "#{line},"
+      end
+    end
+  end
+end

data/lib/json/merge/file_analysis.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Analyzes JSON / JSONC file structure, extracting nodes, comments, and
+    # freeze blocks for merging.
+    class FileAnalysis
+      include Ast::Merge::FileAnalyzable
+
+      DEFAULT_FREEZE_TOKEN = 'json-merge'
+
+      attr_reader :comment_tracker, :ast, :errors, :dialect
+
+      class << self
+        def find_parser_path
+          TreeHaver::GrammarFinder.new(:json).find_library_path
+        end
+      end
+
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil, parser_path: nil, dialect: :jsonc,
+                     **_options)
+        @source = source
+        @lines = source.lines.map(&:chomp)
+        @freeze_token = freeze_token
+        @signature_generator = signature_generator
+        @parser_path = parser_path
+        @dialect = dialect.to_sym
+        @errors = []
+
+        @comment_tracker = CommentTracker.new(source)
+
+        DebugLogger.time('FileAnalysis#parse_json') { parse_json }
+        validate_jsonc_dialect! if valid? && @dialect == :jsonc
+
+        @freeze_blocks = extract_freeze_blocks
+        @nodes = integrate_nodes_and_freeze_blocks
+
+        DebugLogger.debug('FileAnalysis initialized', {
+                            signature_generator: signature_generator ? 'custom' : 'default',
+                            nodes_count: @nodes.size,
+                            freeze_blocks: @freeze_blocks.size,
+                            valid: valid?
+                          })
+      end
+
+      def valid?
+        @errors.empty? && !@ast.nil?
+      end
+
+      def comment_capability
+        @comment_capability ||= comment_tracker.augment(owners: []).capability
+      end
+
+      def comment_support_style
+        @comment_support_style ||= shared_comment_support_style(
+          source: :json_source,
+          style: :c_style_line,
+          read_strategy: :source_augmented_portable_write
+        )
+      end
+
+      def comment_nodes
+        comment_tracker.comment_nodes
+      end
+
+      def comment_node_at(line_num)
+        comment_tracker.comment_node_at(line_num)
+      end
+
+      def comment_region_for_range(range, kind:, full_line_only: false)
+        comment_tracker.comment_region_for_range(
+          range,
+          kind: kind,
+          full_line_only: full_line_only
+        )
+      end
+
+      def comment_augmenter(owners: nil, **options)
+        comment_tracker.augment(
+          owners: owners || comment_augmenter_default_owners,
+          **options
+        )
+      end
+
+      def statements
+        @nodes || []
+      end
+      alias nodes statements
+
+      def in_freeze_block?(line_num)
+        @freeze_blocks.any? { |fb| fb.location.cover?(line_num) }
+      end
+
+      def freeze_block_at(line_num)
+        @freeze_blocks.find { |fb| fb.location.cover?(line_num) }
+      end
+
+      def generate_signature(node)
+        return super if @signature_generator
+        return super unless node.is_a?(NodeWrapper)
+        return super unless node.object?
+
+        return [:root_object] if statements.size == 1 && statements.first == node
+
+        super
+      end
+
+      def fallthrough_node?(value)
+        value.is_a?(NodeWrapper) || value.is_a?(FreezeNode) || super
+      end
+
+      def root_node
+        return @root_node if defined?(@root_node)
+        return @root_node = nil unless valid?
+
+        @root_node = NodeWrapper.new(@ast.root_node, lines: @lines, source: @source, dialect: @dialect)
+      end
+
+      def root_object
+        return @root_object if defined?(@root_object)
+        return @root_object = nil unless valid?
+
+        root = @ast.root_node
+        return @root_object = nil unless root
+
+        root.each do |child|
+          if child.type.to_s == 'object'
+            return @root_object = NodeWrapper.new(child, lines: @lines, source: @source,
+                                                         dialect: @dialect)
+          end
+        end
+
+        @root_object = nil
+      end
+
+      def root_object_open_line
+        obj = root_object
+        return unless obj&.start_line
+
+        line_at(obj.start_line)&.chomp
+      end
+
+      def root_object_close_line
+        obj = root_object
+        return unless obj&.end_line
+
+        line_at(obj.end_line)&.chomp
+      end
+
+      def root_pairs
+        @root_pairs ||= begin
+          obj = root_object
+          obj ? obj.pairs : []
+        end
+      end
+
+      def comment_attachment_for(owner, line_num: nil, **options)
+        shared_comment_attachment_for(
+          owner,
+          tracker_attachment: @comment_tracker.comment_attachment_for(owner, line_num: line_num, **options),
+          line_num: line_num,
+          **options
+        )
+      end
+
+      # @return [Symbol]
+      def comment_attachment_strategy
+        :augmenter_preferred_tracker_layout
+      end
+
+      def ruleset_owner_selector
+        :line_bound_statements
+      end
+
+      def ruleset_render_family
+        :json_object_pairs
+      end
+
+      private
+
+      def layout_augmenter_default_owners
+        pairs = root_pairs.select { |pair| pair.respond_to?(:start_line) && pair.respond_to?(:end_line) }
+        return pairs unless pairs.empty?
+
+        comment_augmenter_default_owners
+      end
+
+      def root_merge_node
+        return unless valid?
+
+        root = @ast.root_node
+        return unless root
+
+        root_type = root.type.to_s
+        return NodeWrapper.new(root, lines: @lines, source: @source, dialect: @dialect) if %w[object
+                                                                                              array].include?(root_type)
+
+        root.each do |child|
+          child_type = child.type.to_s
+          next if child_type == 'comment'
+          next unless %w[object array].include?(child_type)
+
+          return NodeWrapper.new(child, lines: @lines, source: @source, dialect: @dialect)
+        end
+
+        nil
+      end
+
+      def parse_json
+        Json::Merge.register_backend!
+        parser = TreeHaver.parser_for(parser_language, backend_type: :tree_sitter)
+
+        @ast = parser.parse(@source)
+
+        collect_parse_errors(@ast.root_node) if @ast&.root_node
+      rescue TreeHaver::Error => e
+        @errors << e
+        @ast = nil
+      rescue StandardError => e
+        @errors << e
+        @ast = nil
+      end
+
+      def parser_language
+        %i[jsonc json5].include?(@dialect) ? :json5 : :json
+      end
+
+      def validate_jsonc_dialect!
+        validate_jsonc_node!(@ast.root_node)
+      end
+
+      def validate_jsonc_node!(node)
+        native_type = node.respond_to?(:native_type) ? node.native_type.to_s : node.type.to_s
+        case native_type
+        when 'identifier'
+          add_jsonc_dialect_error(node, 'unquoted object keys are JSON5-only')
+        when 'string'
+          validate_json_literal!(node, String, 'single-quoted strings and JSON5 escapes are not supported')
+        when 'number'
+          validate_json_literal!(node, Numeric, 'JSON5 numeric literals are not supported')
+        end
+
+        node.each { |child| validate_jsonc_node!(child) } if node.respond_to?(:each)
+      end
+
+      # Tree-sitter identifies complete string and number tokens. Delegating those
+      # token semantics to Ruby's strict JSON parser avoids a second hand-written
+      # lexer while retaining AST-derived source locations.
+      def validate_json_literal!(node, expected_class, reason)
+        value = ::JSON.parse(node.text)
+        return if value.is_a?(expected_class)
+
+        add_jsonc_dialect_error(node, reason)
+      rescue ::JSON::ParserError
+        add_jsonc_dialect_error(node, reason)
+      end
+
+      def add_jsonc_dialect_error(node, reason)
+        @errors << Json::Merge::JsoncDialectError.new(
+          "JSONC rejects #{reason} at line #{node.start_line}, column #{node.start_point[:column] + 1}."
+        )
+      end
+
+      def collect_parse_errors(node, found_errors = [])
+        if node.type.to_s == 'ERROR' ||
+           (node.respond_to?(:has_error?) && node.has_error?) ||
+           (node.respond_to?(:missing?) && node.missing?)
+          found_errors << {
+            type: node.type.to_s,
+            start_point: node.respond_to?(:start_point) ? node.start_point : nil,
+            end_point: node.respond_to?(:end_point) ? node.end_point : nil,
+            text: node.to_s
+          }
+        end
+
+        node.each { |child| collect_parse_errors(child, found_errors) } if node.respond_to?(:each)
+        @errors.concat(found_errors) unless found_errors.empty?
+        found_errors
+      end
+
+      def extract_freeze_blocks
+        freeze_starts = []
+        freeze_ends = []
+
+        single_line_pattern = %r{^\s*//\s*#{Regexp.escape(@freeze_token)}:(freeze|unfreeze)\b}i
+        block_pattern = %r{^\s*/\*\s*#{Regexp.escape(@freeze_token)}:(freeze|unfreeze)\b.*\*/}i
+
+        @lines.each_with_index do |line, idx|
+          line_num = idx + 1
+
+          marker_type = nil
+          if (match = line.match(single_line_pattern))
+            marker_type = match[1]&.downcase
+          elsif (match = line.match(block_pattern))
+            marker_type = match[1]&.downcase
+          end
+
+          next unless marker_type
+
+          if marker_type == 'freeze'
+            freeze_starts << { line: line_num, marker: line }
+          elsif marker_type == 'unfreeze'
+            freeze_ends << { line: line_num, marker: line }
+          end
+        end
+
+        blocks = []
+        freeze_starts.each do |start_info|
+          matching_end = freeze_ends.find { |ending| ending[:line] > start_info[:line] }
+          next unless matching_end
+
+          freeze_ends.delete(matching_end)
+          blocks << FreezeNode.new(
+            start_line: start_info[:line],
+            end_line: matching_end[:line],
+            lines: @lines,
+            start_marker: start_info[:marker],
+            end_marker: matching_end[:marker]
+          )
+        end
+
+        blocks
+      end
+
+      def integrate_nodes_and_freeze_blocks
+        return @freeze_blocks.dup unless valid?
+
+        result = []
+        processed_lines = ::Set.new
+
+        @freeze_blocks.each do |fb|
+          (fb.start_line..fb.end_line).each { |ln| processed_lines << ln }
+          result << fb
+        end
+
+        root = root_merge_node
+        if root&.start_line
+          root_lines = (root.start_line..root.end_line).to_a
+          result << root unless root_lines.any? { |ln| processed_lines.include?(ln) }
+        end
+
+        result.sort_by { |node| node&.start_line || 0 }
+      end
+
+      def compute_node_signature(node)
+        case node
+        when FreezeNode
+          node.signature
+        when NodeWrapper
+          node.signature
+        end
+      end
+    end
+  end
+end

data/lib/json/merge/freeze_node.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Json
+  module Merge
+    # Wrapper to represent comment-marked freeze blocks as first-class nodes in
+    # JSON / JSONC files.
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      InvalidStructureError = Ast::Merge::FreezeNodeBase::InvalidStructureError
+      Location = Ast::Merge::FreezeNodeBase::Location
+
+      def initialize(start_line:, end_line:, lines:, start_marker: nil, end_marker: nil, pattern_type: :c_style_line)
+        block_lines = (start_line..end_line).map { |ln| lines[ln - 1] }
+
+        super(
+          start_line: start_line,
+          end_line: end_line,
+          lines: block_lines,
+          start_marker: start_marker,
+          end_marker: end_marker,
+          pattern_type: pattern_type,
+        )
+
+        validate_structure!
+      end
+
+      def signature
+        normalized = @lines.map { |line| line&.strip }.compact.reject(&:empty?).join("\n")
+        [:FreezeNode, normalized]
+      end
+
+      def object?
+        false
+      end
+
+      def array?
+        false
+      end
+
+      def pair?
+        false
+      end
+
+      def inspect
+        "#<#{self.class.name} lines=#{start_line}..#{end_line} content_length=#{slice&.length || 0}>"
+      end
+
+      private
+
+      def validate_structure!
+        validate_line_order!
+
+        return unless @lines.empty? || @lines.all?(&:nil?)
+
+        raise InvalidStructureError.new(
+          'Freeze block is empty',
+          start_line: @start_line,
+          end_line: @end_line
+        )
+      end
+    end
+  end
+end