jsonc-merge 1.0.0

data/lib/jsonc/merge/debug_logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Debug logging utility for Jsonc::Merge.
+    # Extends the base Ast::Merge::DebugLogger with Jsonc-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
+
+      # Jsonc-specific configuration
+      self.env_var_name = "JSONC_MERGE_DEBUG"
+      self.log_prefix = "[Jsonc::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 Jsonc::Merge::FreezeNode
+            {type: "FreezeNode", lines: "#{node.start_line}..#{node.end_line}"}
+          when Jsonc::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/jsonc/merge/emitter.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Jsonc
+  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
+      # @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
+      end
+
+      # Clear subclass-specific state
+      def clear_subclass_state
+        @needs_comma = false
+      end
+
+      # Emit a tracked comment from CommentTracker
+      # @param comment [Hash] Comment with :text, :indent, :block
+      def emit_tracked_comment(comment)
+        indent = " " * (comment[:indent] || 0)
+        @lines << 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
+          @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 object start
+      def emit_object_start
+        add_comma_if_needed
+        @lines << "#{current_indent}{"
+        indent
+        @needs_comma = false
+      end
+
+      # Emit object end
+      def emit_object_end
+        dedent
+        @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
+        @needs_comma = false
+      end
+
+      # Emit array end
+      def emit_array_end
+        dedent
+        @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 a key with opening brace for nested object
+      # @param key [String] Key name
+      def emit_nested_object_start(key)
+        add_comma_if_needed
+        @lines << "#{current_indent}\"#{key}\": {"
+        indent
+        @needs_comma = false
+      end
+
+      # Emit closing brace for nested object
+      def emit_nested_object_end
+        dedent
+        @lines << "#{current_indent}}"
+        @needs_comma = true
+      end
+
+      # Get the output as a JSON string
+      #
+      # @return [String]
+      def to_json
+        to_s
+      end
+
+      private
+
+      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

data/lib/jsonc/merge/file_analysis.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Analyzes JSON/JSONC file structure, extracting nodes, comments, and freeze blocks.
+    # This is the main analysis class that prepares JSON content for merging.
+    #
+    # Supports JSONC (JSON with Comments) which allows single-line (//) and
+    # multi-line (/* */) comments in JSON files. This is commonly used in
+    # configuration files like tsconfig.json, VS Code settings, etc.
+    #
+    # @example Basic usage
+    #   analysis = FileAnalysis.new(json_source)
+    #   analysis.valid? # => true
+    #   analysis.nodes # => [NodeWrapper, FreezeNodeBase, ...]
+    #   analysis.freeze_blocks # => [FreezeNodeBase, ...]
+    class FileAnalysis
+      include Ast::Merge::FileAnalyzable
+
+      # Default freeze token for identifying freeze blocks
+      DEFAULT_FREEZE_TOKEN = "json-merge"
+
+      # @return [CommentTracker] Comment tracker for this file
+      attr_reader :comment_tracker
+
+      # @return [TreeHaver::Tree, nil] Parsed AST
+      attr_reader :ast
+
+      # @return [Array] Parse errors if any
+      attr_reader :errors
+
+      class << self
+        # Find the parser library path using TreeHaver::GrammarFinder
+        #
+        # Note: JSONC uses the tree-sitter-jsonc grammar (supports JSON with Comments)
+        #
+        # @return [String, nil] Path to the parser library or nil if not found
+        def find_parser_path
+          TreeHaver::GrammarFinder.new(:jsonc).find_library_path
+        end
+      end
+
+      # Initialize file analysis
+      #
+      # @param source [String] JSON/JSONC source code to analyze
+      # @param freeze_token [String] Token for freeze block markers
+      # @param signature_generator [Proc, nil] Custom signature generator
+      # @param parser_path [String, nil] Path to tree-sitter-json parser library
+      # @param options [Hash] Additional options (forward compatibility - ignored by FileAnalysis)
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil, parser_path: nil, **options)
+        @source = source
+        @lines = source.lines.map(&:chomp)
+        @freeze_token = freeze_token
+        @signature_generator = signature_generator
+        @parser_path = parser_path || self.class.find_parser_path
+        @errors = []
+        # **options captures any additional parameters (e.g., node_typing) for forward compatibility
+
+        # Initialize comment tracking
+        @comment_tracker = CommentTracker.new(source)
+
+        # Parse the JSON
+        DebugLogger.time("FileAnalysis#parse_json") { parse_json }
+
+        # Extract freeze blocks and integrate with nodes
+        @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
+
+      # Check if parse was successful
+      # @return [Boolean]
+      def valid?
+        @errors.empty? && !@ast.nil?
+      end
+
+      # The base module uses 'statements' - provide both names for compatibility
+      # @return [Array<NodeWrapper, FreezeNode>]
+      def statements
+        @nodes ||= []
+      end
+
+      # Alias for convenience - json-merge prefers "nodes" terminology
+      alias_method :nodes, :statements
+
+      # Check if a line is within a freeze block.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def in_freeze_block?(line_num)
+        @freeze_blocks.any? { |fb| fb.location.cover?(line_num) }
+      end
+
+      # Get the freeze block containing the given line.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [FreezeNode, nil]
+      def freeze_block_at(line_num)
+        @freeze_blocks.find { |fb| fb.location.cover?(line_num) }
+      end
+
+      # Override to handle special signature generation for root-level objects
+      # When there's only one root object, we want it to match regardless of keys
+      # so that add_template_only_nodes can work properly
+      def generate_signature(node)
+        # If custom signature generator provided, let it handle everything
+        return super if @signature_generator
+
+        return super unless node.is_a?(NodeWrapper)
+        return super unless node.object?
+
+        # Check if this is the sole root object
+        if statements.size == 1 && statements.first == node
+          # Root object gets a consistent signature so they always match
+          return [:root_object]
+        end
+
+        super
+      end
+
+      # Override to detect tree-sitter nodes for signature generator fallthrough
+      # @param value [Object] The value to check
+      # @return [Boolean] true if this is a fallthrough node
+      def fallthrough_node?(value)
+        value.is_a?(NodeWrapper) || value.is_a?(FreezeNode) || super
+      end
+
+      # Get the root node of the parse tree
+      # @return [NodeWrapper, nil]
+      def root_node
+        return unless valid?
+
+        NodeWrapper.new(@ast.root_node, lines: @lines, source: @source)
+      end
+
+      # Get the root object if the JSON document is an object
+      # @return [NodeWrapper, nil]
+      def root_object
+        return unless valid?
+
+        root = @ast.root_node
+        return unless root
+
+        # JSON root should be a document containing an object or array
+        root.each do |child|
+          if child.type.to_s == "object"
+            return NodeWrapper.new(child, lines: @lines, source: @source)
+          end
+        end
+        nil
+      end
+
+      # Get the opening brace line of the root object (the line containing `{`)
+      # @return [String, nil]
+      def root_object_open_line
+        obj = root_object
+        return unless obj&.start_line
+
+        line_at(obj.start_line)&.chomp
+      end
+
+      # Get the closing brace line of the root object (the line containing `}`)
+      # @return [String, nil]
+      def root_object_close_line
+        obj = root_object
+        return unless obj&.end_line
+
+        line_at(obj.end_line)&.chomp
+      end
+
+      # Get key-value pairs from the root object
+      # @return [Array<NodeWrapper>]
+      def root_pairs
+        obj = root_object
+        return [] unless obj
+
+        obj.pairs
+      end
+
+      private
+
+      def parse_json
+        # Use TreeHaver's high-level API - it handles:
+        # - Grammar auto-discovery
+        # - Backend selection
+        # - Explicit path validation (raises NotAvailable if path doesn't exist)
+        # Note: JSONC uses the tree-sitter-jsonc grammar (supports JSON with Comments)
+        parser = TreeHaver.parser_for(:jsonc, library_path: @parser_path)
+
+        @ast = parser.parse(@source)
+
+        # Check for parse errors in the tree
+        # Note: Some backends (Java/jtreesitter) may not set has_error? correctly,
+        # so we always collect errors if present, regardless of has_error? return value
+        if @ast&.root_node
+          # Collect parse errors from the AST
+          # This works whether has_error? is supported or not
+          collect_parse_errors(@ast.root_node)
+        end
+      rescue TreeHaver::Error => e
+        # TreeHaver::Error inherits from Exception, not StandardError.
+        # This also catches TreeHaver::NotAvailable (subclass of Error).
+        @errors << e.message
+        @ast = nil
+      rescue StandardError => e
+        @errors << e
+        @ast = nil
+      end
+
+      def collect_parse_errors(node, found_errors = [])
+        # Collect ERROR and MISSING nodes from the tree
+        if node.type.to_s == "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)
+
+        # Add found errors to @errors
+        @errors.concat(found_errors) unless found_errors.empty?
+
+        found_errors
+      end
+
+      def extract_freeze_blocks
+        # JSONC supports both // and /* */ comments
+        # We look for freeze markers in both styles
+        freeze_starts = []
+        freeze_ends = []
+
+        # Pattern for single-line comments: // json-merge:freeze
+        single_line_pattern = %r{^\s*//\s*#{Regexp.escape(@freeze_token)}:(freeze|unfreeze)\b}i
+
+        # Pattern for block comments: /* json-merge:freeze */
+        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
+
+        # Match freeze starts with ends
+        blocks = []
+        freeze_starts.each do |start_info|
+          # Find the next unfreeze after this freeze
+          matching_end = freeze_ends.find { |e| e[:line] > start_info[:line] }
+          next unless matching_end
+
+          # Remove used end marker
+          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
+
+        # Mark freeze block lines as processed
+        @freeze_blocks.each do |fb|
+          (fb.start_line..fb.end_line).each { |ln| processed_lines << ln }
+          result << fb
+        end
+
+        # Add the root object/array if it exists and isn't in a freeze block
+        # This is the top-level structural node that should be merged
+        root = root_object
+        if root&.start_line
+          # Check if root is in a freeze block
+          root_lines = (root.start_line..root.end_line).to_a
+          unless root_lines.any? { |ln| processed_lines.include?(ln) }
+            result << root
+          end
+        end
+
+        # Sort by start line
+        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/jsonc/merge/freeze_node.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Wrapper to represent freeze blocks as first-class nodes in JSON/JSONC files.
+    # A freeze block is a section marked with freeze/unfreeze comment markers that
+    # should be preserved from the destination during merges.
+    #
+    # Inherits from Ast::Merge::FreezeNodeBase for shared functionality including
+    # the Location struct, InvalidStructureError, and configurable marker patterns.
+    #
+    # Uses the `:c_style_line` or `:c_style_block` pattern types for JSONC files
+    # (// comments and /* */ comments).
+    #
+    # @example Freeze block with single-line comments
+    #   // json-merge:freeze
+    #   "secret_key": "my-secret-value",
+    #   "api_endpoint": "https://custom.example.com"
+    #   // json-merge:unfreeze
+    #
+    # @example Freeze block with block comments
+    #   /* json-merge:freeze */
+    #   "secret_key": "my-secret-value"
+    #   /* json-merge:unfreeze */
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      # Inherit InvalidStructureError from base class
+      InvalidStructureError = Ast::Merge::FreezeNodeBase::InvalidStructureError
+
+      # Inherit Location from base class
+      Location = Ast::Merge::FreezeNodeBase::Location
+
+      # @param start_line [Integer] Line number of freeze marker
+      # @param end_line [Integer] Line number of unfreeze marker
+      # @param lines [Array<String>] All source lines
+      # @param start_marker [String, nil] The freeze start marker text
+      # @param end_marker [String, nil] The freeze end marker text
+      # @param pattern_type [Symbol] Pattern type for marker matching (defaults to :c_style_line)
+      def initialize(start_line:, end_line:, lines:, start_marker: nil, end_marker: nil, pattern_type: :c_style_line)
+        # Extract lines for the entire block (lines param is all source lines)
+        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
+
+      # Returns a stable signature for this freeze block.
+      # Signature includes the normalized content to detect changes.
+      # @return [Array] Signature array
+      def signature
+        # Normalize by stripping each line and joining
+        normalized = @lines.map { |l| l&.strip }.compact.reject(&:empty?).join("\n")
+        [:FreezeNode, normalized]
+      end
+
+      # Check if this is an object node (always false for FreezeNode)
+      # @return [Boolean]
+      def object?
+        false
+      end
+
+      # Check if this is an array node (always false for FreezeNode)
+      # @return [Boolean]
+      def array?
+        false
+      end
+
+      # Check if this is a pair node (always false for FreezeNode)
+      # @return [Boolean]
+      def pair?
+        false
+      end
+
+      # String representation for debugging
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} lines=#{start_line}..#{end_line} content_length=#{slice&.length || 0}>"
+      end
+
+      private
+
+      def validate_structure!
+        validate_line_order!
+
+        if @lines.empty? || @lines.all?(&:nil?)
+          raise InvalidStructureError.new(
+            "Freeze block is empty",
+            start_line: @start_line,
+            end_line: @end_line,
+          )
+        end
+      end
+    end
+  end
+end