jsonc-merge 1.0.0

data/lib/jsonc/merge/merge_result.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Tracks the result of a merge operation, including the merged content,
+    # decisions made, and statistics.
+    #
+    # Inherits decision constants and base functionality from Ast::Merge::MergeResult.
+    #
+    # @example Basic usage
+    #   result = MergeResult.new
+    #   result.add_line('"key": "value"', decision: :kept_template, source: :template)
+    #   result.to_json # => '"key": "value"\n'
+    class MergeResult < Ast::Merge::MergeResultBase
+      # Inherit decision constants from base class
+      DECISION_KEPT_TEMPLATE = Ast::Merge::MergeResultBase::DECISION_KEPT_TEMPLATE
+      DECISION_KEPT_DEST = Ast::Merge::MergeResultBase::DECISION_KEPT_DEST
+      DECISION_MERGED = Ast::Merge::MergeResultBase::DECISION_MERGED
+      DECISION_ADDED = Ast::Merge::MergeResultBase::DECISION_ADDED
+      DECISION_FREEZE_BLOCK = Ast::Merge::MergeResultBase::DECISION_FREEZE_BLOCK
+
+      # @return [Hash] Statistics about the merge
+      attr_reader :statistics
+
+      # Initialize a new merge result
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(**options)
+        super(**options)
+        @statistics = {
+          template_lines: 0,
+          dest_lines: 0,
+          merged_lines: 0,
+          freeze_preserved_lines: 0,
+          total_decisions: 0,
+        }
+      end
+
+      # Add a single line to the result
+      #
+      # @param line [String] Line content
+      # @param decision [Symbol] Decision that led to this line
+      # @param source [Symbol] Source of the line (:template, :destination, :merged)
+      # @param original_line [Integer, nil] Original line number
+      def add_line(line, decision:, source:, original_line: nil)
+        @lines << {
+          content: line,
+          decision: decision,
+          source: source,
+          original_line: original_line,
+        }
+
+        track_statistics(decision, source)
+        track_decision(decision, source, line: original_line)
+      end
+
+      # Add multiple lines to the result
+      #
+      # @param lines [Array<String>] Lines to add
+      # @param decision [Symbol] Decision for all lines
+      # @param source [Symbol] Source of the lines
+      # @param start_line [Integer, nil] Starting original line number
+      def add_lines(lines, decision:, source:, start_line: nil)
+        lines.each_with_index do |line, idx|
+          original_line = start_line ? start_line + idx : nil
+          add_line(line, decision: decision, source: source, original_line: original_line)
+        end
+      end
+
+      # Add a blank line
+      #
+      # @param decision [Symbol] Decision for the blank line
+      # @param source [Symbol] Source
+      def add_blank_line(decision: DECISION_MERGED, source: :merged)
+        add_line("", decision: decision, source: source)
+      end
+
+      # Add content from a freeze block
+      #
+      # @param freeze_node [FreezeNode] Freeze block to add
+      def add_freeze_block(freeze_node)
+        freeze_node.lines.each_with_index do |line, idx|
+          add_line(
+            line.chomp,
+            decision: DECISION_FREEZE_BLOCK,
+            source: :destination,
+            original_line: freeze_node.start_line + idx,
+          )
+        end
+      end
+
+      # Add content from a node wrapper
+      #
+      # @param node [NodeWrapper] Node to add
+      # @param decision [Symbol] Decision that led to keeping this node
+      # @param source [Symbol] Source of the node
+      # @param analysis [FileAnalysis] Analysis for accessing source lines
+      def add_node(node, decision:, source:, analysis:)
+        return unless node.start_line && node.end_line
+
+        (node.start_line..node.end_line).each do |line_num|
+          line = analysis.line_at(line_num)
+          next unless line
+
+          add_line(line.chomp, decision: decision, source: source, original_line: line_num)
+        end
+      end
+
+      # Get the merged content as a JSON string
+      #
+      # @return [String]
+      def to_json
+        content = @lines.map { |l| l[:content] }.join("\n")
+        # Ensure trailing newline
+        content += "\n" unless content.end_with?("\n") || content.empty?
+        content
+      end
+
+      # Alias for to_json
+      # @return [String]
+      def content
+        to_json
+      end
+
+      # Alias for to_json (used by SmartMerger#merge)
+      # @return [String]
+      def to_s
+        to_json
+      end
+
+      # Get line count
+      # @return [Integer]
+      def line_count
+        @lines.size
+      end
+
+      private
+
+      def track_statistics(decision, source)
+        @statistics[:total_decisions] += 1
+
+        case decision
+        when DECISION_KEPT_TEMPLATE
+          @statistics[:template_lines] += 1
+        when DECISION_KEPT_DEST
+          @statistics[:dest_lines] += 1
+        when DECISION_FREEZE_BLOCK
+          @statistics[:freeze_preserved_lines] += 1
+        else
+          @statistics[:merged_lines] += 1
+        end
+      end
+    end
+  end
+end

data/lib/jsonc/merge/node_wrapper.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Wraps TreeHaver nodes with comment associations, line information, and signatures.
+    # This provides a unified interface for working with JSONC (JSON with Comments) AST nodes during merging.
+    #
+    # Inherits common functionality from Ast::Merge::NodeWrapperBase:
+    # - Source context (lines, source, comments)
+    # - Line info extraction
+    # - Basic methods: #type, #type?, #text, #content, #signature
+    #
+    # @example Basic usage
+    #   parser = TreeHaver::Parser.new
+    #   parser.language = TreeHaver::Language.jsonc
+    #   tree = parser.parse(source)
+    #   wrapper = NodeWrapper.new(tree.root_node, lines: source.lines, source: source)
+    #   wrapper.signature # => [:object, ...]
+    #
+    # @see Ast::Merge::NodeWrapperBase
+    class NodeWrapper < Ast::Merge::NodeWrapperBase
+      # Check if this is a JSON object
+      # @return [Boolean]
+      def object?
+        @node.type.to_s == "object"
+      end
+
+      # Check if this is a JSON array
+      # @return [Boolean]
+      def array?
+        @node.type.to_s == "array"
+      end
+
+      # Check if this is a JSON string
+      # @return [Boolean]
+      def string?
+        @node.type.to_s == "string"
+      end
+
+      # Check if this is a JSON number
+      # @return [Boolean]
+      def number?
+        @node.type.to_s == "number"
+      end
+
+      # Check if this is a JSON boolean (true/false)
+      # @return [Boolean]
+      def boolean?
+        %w[true false].include?(@node.type.to_s)
+      end
+
+      # Check if this is a JSON null
+      # @return [Boolean]
+      def null?
+        @node.type.to_s == "null"
+      end
+
+      # Check if this is a key-value pair
+      # @return [Boolean]
+      def pair?
+        @node.type.to_s == "pair"
+      end
+
+      # Check if this is a comment
+      # @return [Boolean]
+      def comment?
+        @node.type.to_s == "comment"
+      end
+
+      # Get the key name if this is a pair node
+      # @return [String, nil]
+      def key_name
+        return unless pair?
+
+        # In JSONC tree-sitter, pair has key and value children
+        key_node = find_child_by_field("key")
+
+        return unless key_node
+
+        # Key is typically a string, extract its content without quotes using byte positions
+        key_text = node_text(key_node)
+        # Remove surrounding quotes if present
+        key_text&.gsub(/\A"|"\z/, "")
+      end
+
+      # Get the value node if this is a pair
+      # @return [NodeWrapper, nil]
+      def value_node
+        return unless pair?
+
+        value = find_child_by_field("value")
+
+        return unless value
+
+        NodeWrapper.new(value, lines: @lines, source: @source)
+      end
+
+      # Get key-value pairs if this is an object
+      # @return [Array<NodeWrapper>]
+      def pairs
+        return [] unless object?
+
+        result = []
+        @node.each do |child|
+          next if child.type.to_s == "comment"
+          next unless child.type.to_s == "pair"
+
+          result << NodeWrapper.new(child, lines: @lines, source: @source)
+        end
+        result
+      end
+
+      # Get array elements if this is an array
+      # @return [Array<NodeWrapper>]
+      def elements
+        return [] unless array?
+
+        result = []
+        @node.each do |child|
+          child_type = child.type.to_s
+          # Skip punctuation and comments
+          next if child_type == "comment"
+          next if child_type == ","
+          next if child_type == "["
+          next if child_type == "]"
+
+          result << NodeWrapper.new(child, lines: @lines, source: @source)
+        end
+        result
+      end
+
+      # Get mergeable children - the semantically meaningful children for tree merging
+      # For objects, returns pairs. For arrays, returns elements.
+      # For other node types, returns empty array (leaf nodes).
+      # @return [Array<NodeWrapper>]
+      def mergeable_children
+        case type
+        when :object
+          pairs
+        when :array
+          elements
+        else
+          []
+        end
+      end
+
+      # Check if this node is a container (has mergeable children)
+      # @return [Boolean]
+      def container?
+        object? || array?
+      end
+
+      # Check if this is a root-level container (direct child of document)
+      # Root-level containers get a generic signature so they always match.
+      # @return [Boolean]
+      def root_level_container?
+        return false unless container?
+
+        # Check if parent is a document node
+        parent_node = @node.parent if @node.respond_to?(:parent)
+        return false unless parent_node
+
+        parent_node.type.to_s == "document"
+      end
+
+      # Get the opening line for a container node (the line with { or [)
+      # For multi-line containers, returns the full line.
+      # For single-line containers, returns just the opening bracket to avoid duplicating content.
+      # @return [String, nil]
+      def opening_line
+        return unless container? && @start_line
+
+        # If this is a single-line container, just return the opening bracket
+        if @start_line == @end_line
+          return opening_bracket
+        end
+
+        @lines[@start_line - 1]
+      end
+
+      # Get the closing line for a container node (the line with } or ])
+      # For multi-line containers, returns the full line.
+      # For single-line containers, returns just the closing bracket to avoid duplicating content.
+      # @return [String, nil]
+      def closing_line
+        return unless container? && @end_line
+
+        # If this is a single-line container, just return the closing bracket
+        if @start_line == @end_line
+          return closing_bracket
+        end
+
+        @lines[@end_line - 1]
+      end
+
+      # Get the opening bracket character for this container
+      # @return [String, nil]
+      def opening_bracket
+        return "{" if object?
+        return "[" if array?
+
+        nil
+      end
+
+      # Get the closing bracket character for this container
+      # @return [String, nil]
+      def closing_bracket
+        return "}" if object?
+        return "]" if array?
+
+        nil
+      end
+
+      # Find a child by field name
+      # @param field_name [String] Field name to look for
+      # @return [TreeSitter::Node, nil]
+      def find_child_by_field(field_name)
+        return unless @node.respond_to?(:child_by_field_name)
+
+        @node.child_by_field_name(field_name)
+      end
+
+      # Find a child by type
+      # @param type_name [String] Type name to look for
+      # @return [TreeSitter::Node, nil]
+      def find_child_by_type(type_name)
+        return unless @node.respond_to?(:each)
+
+        @node.each do |child|
+          return child if child.type.to_s == type_name
+        end
+        nil
+      end
+
+      protected
+
+      # Override wrap_child to use Jsonc::Merge::NodeWrapper
+      def wrap_child(child)
+        NodeWrapper.new(child, lines: @lines, source: @source)
+      end
+
+      def compute_signature(node)
+        node_type = node.type.to_s
+
+        case node_type
+        when "document"
+          # Root document - signature based on root content type
+          child = nil
+          node.each { |c|
+            child = c unless c.type.to_s == "comment"
+            break if child
+          }
+          child_type = child&.type&.to_s
+          [:document, child_type]
+        when "object"
+          # For root-level objects (direct child of document), use a generic signature
+          # that always matches so merging happens at the pair level.
+          if root_level_container?
+            [:root_object]
+          else
+            # Nested objects identified by their keys
+            keys = extract_object_keys(node)
+            [:object, keys.sort]
+          end
+        when "array"
+          # For root-level arrays (direct child of document), use a generic signature
+          if root_level_container?
+            [:root_array]
+          else
+            # Nested arrays identified by their length and first few elements
+            elements_count = 0
+            node.each { |c| elements_count += 1 unless %w[comment , \[ \]].include?(c.type.to_s) }
+            [:array, elements_count]
+          end
+        when "pair"
+          # Pairs identified by their key name
+          key = key_name
+          [:pair, key]
+        when "string"
+          # Strings identified by their content
+          [:string, node_text(node)]
+        when "number"
+          # Numbers identified by their value
+          [:number, node_text(node)]
+        when "true", "false"
+          # Booleans
+          [:boolean, node.type.to_s]
+        when "null"
+          [:null]
+        when "comment"
+          # Comments identified by their content
+          [:comment, node_text(node)&.strip]
+        else
+          # Generic fallback
+          content_preview = node_text(node)&.slice(0, 50)&.strip
+          [node_type.to_sym, content_preview]
+        end
+      end
+
+      private
+
+      def extract_object_keys(object_node)
+        keys = []
+        object_node.each do |child|
+          next unless child.type.to_s == "pair"
+
+          key_node = child.respond_to?(:child_by_field_name) ? child.child_by_field_name("key") : nil
+
+          # Fallback for backends without field access (FFI)
+          unless key_node
+            child.each do |pair_child|
+              pair_child_type = pair_child.type.to_s
+              next if pair_child_type == ":" || pair_child_type == "comment"
+              key_node = pair_child
+              break
+            end
+          end
+
+          next unless key_node
+
+          key_text = node_text(key_node)&.gsub(/\A"|"\z/, "")
+          keys << key_text if key_text
+        end
+        keys
+      end
+    end
+  end
+end

data/lib/jsonc/merge/smart_merger.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # High-level merger for JSONC (JSON with Comments) content.
+    # Orchestrates parsing, analysis, and conflict resolution.
+    #
+    # @example Basic usage
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   merged_string = merger.merge
+    #   File.write("merged.jsonc", merged_string)
+    #
+    # @example With full result object
+    #   merger = SmartMerger.new(template, dest)
+    #   result = merger.merge_result
+    #   puts result.statistics
+    #   File.write("merged.jsonc", result.content)
+    #
+    # @example With options
+    #   merger = SmartMerger.new(template, dest,
+    #     preference: :template,
+    #     add_template_only_nodes: true)
+    #   merged_string = merger.merge
+    #
+    # @example With node_typing for per-node-type preferences
+    #   merger = SmartMerger.new(template, dest,
+    #     node_typing: { "object" => ->(n) { NodeTyping.with_merge_type(n, :config) } },
+    #     preference: { default: :destination, config: :template })
+    class SmartMerger < ::Ast::Merge::SmartMergerBase
+      # Creates a new SmartMerger
+      #
+      # @param template_content [String] Template JSONC content
+      # @param dest_content [String] Destination JSONC 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 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,
+        freeze_token: nil,
+        match_refiner: nil,
+        regions: nil,
+        region_placeholder: nil,
+        node_typing: nil,
+        **options
+      )
+        super(
+          template_content,
+          dest_content,
+          signature_generator: signature_generator,
+          preference: preference,
+          add_template_only_nodes: add_template_only_nodes,
+          freeze_token: freeze_token,
+          match_refiner: match_refiner,
+          regions: regions,
+          region_placeholder: region_placeholder,
+          node_typing: node_typing,
+          **options
+        )
+      end
+
+      # Backward-compatible options hash
+      #
+      # @return [Hash] The merge options
+      def options
+        {
+          preference: @preference,
+          add_template_only_nodes: @add_template_only_nodes,
+          match_refiner: @match_refiner,
+        }
+      end
+
+      protected
+
+      # @return [Class] The analysis class for JSONC files
+      def analysis_class
+        FileAnalysis
+      end
+
+      # @return [String] The default freeze token
+      def default_freeze_token
+        "jsonc-merge"
+      end
+
+      # @return [Class] The resolver class for JSONC files
+      def resolver_class
+        ConflictResolver
+      end
+
+      # @return [Class] The result class for JSONC files
+      def result_class
+        MergeResult
+      end
+
+      # Perform the JSONC-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 JSONC-specific configuration
+      def build_resolver
+        ConflictResolver.new(
+          @template_analysis,
+          @dest_analysis,
+          preference: @preference,
+          add_template_only_nodes: @add_template_only_nodes,
+          match_refiner: @match_refiner,
+          node_typing: @node_typing,
+        )
+      end
+
+      # Build the result (no-arg constructor for JSONC)
+      def build_result
+        MergeResult.new
+      end
+
+      # @return [Class] The template parse error class for JSONC
+      def template_parse_error_class
+        TemplateParseError
+      end
+
+      # @return [Class] The destination parse error class for JSONC
+      def destination_parse_error_class
+        DestinationParseError
+      end
+
+      private
+
+      # JSONC FileAnalysis only accepts signature_generator, not freeze_token
+      def build_full_analysis_options
+        {signature_generator: @signature_generator}
+      end
+    end
+  end
+end

data/lib/jsonc/merge/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Jsonc
+  module Merge
+    # Version information for Jsonc::Merge
+    module Version
+      # Current version of the json-merge gem
+      VERSION = "1.0.0"
+    end
+    VERSION = Version::VERSION # traditional location
+  end
+end