toml-merge 1.0.0 → 2.0.0

data/lib/toml/merge/conflict_resolver.rb

@@ -8,7 +8,7 @@ module Toml
     # @example Basic usage
     #   resolver = ConflictResolver.new(template_analysis, dest_analysis)
     #   resolver.resolve(result)
-    class ConflictResolver < ::Ast::Merge::ConflictResolverBase
+    class ConflictResolver < Ast::Merge::ConflictResolverBase
       # Creates a new ConflictResolver
       #
       # @param template_analysis [FileAnalysis] Analyzed template file
@@ -19,15 +19,18 @@ module Toml
       #   - :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
-      def initialize(template_analysis, dest_analysis, preference: :destination, add_template_only_nodes: false, match_refiner: nil)
+      # @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
+          add_template_only_nodes: add_template_only_nodes,
+          match_refiner: match_refiner,
+          **options
         )
-        @match_refiner = match_refiner
+        @emitter = Emitter.new
       end
 
       protected
@@ -40,15 +43,25 @@ module Toml
           template_statements = @template_analysis.statements
           dest_statements = @dest_analysis.statements
 
-          # Merge root-level statements (tables, array_of_tables, pairs)
-          merge_node_lists(
+          # 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,
-            result,
           )
 
+          # Transfer emitter output to result
+          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,
@@ -59,13 +72,12 @@ module Toml
 
       private
 
-      # Recursively merge two lists of nodes (tree-based merge)
+      # 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
-      # @param result [MergeResult] Result to populate
-      def merge_node_lists(template_nodes, dest_nodes, template_analysis, dest_analysis, result)
+      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)
@@ -82,20 +94,13 @@ module Toml
         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)
+            # Both have this node - merge them
+            merge_matched_nodes_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
 
             processed_dest_sigs << dest_sig
             processed_template_sigs << dest_sig
@@ -105,13 +110,13 @@ module Toml
             template_sig = template_analysis.generate_signature(template_node)
 
             # Merge matched nodes
-            merge_matched_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
+            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
-            add_node_to_result(dest_node, result, :destination, MergeResult::DECISION_KEPT_DEST, dest_analysis)
+            emit_node(dest_node, dest_analysis)
             processed_dest_sigs << dest_sig if dest_sig
           end
         end
@@ -125,38 +130,56 @@ module Toml
           # 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)
+          emit_node(template_node, template_analysis)
           processed_template_sigs << template_sig if template_sig
         end
       end
 
-      # Merge two matched nodes - for containers, recursively merge children
+      # Merge two matched nodes
       # @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)
+      def merge_matched_nodes_to_emitter(template_node, dest_node, template_analysis, dest_analysis)
+        # For TOML, tables can be merged recursively
         if dest_node.table? && template_node.table?
-          # Both are tables - merge their contents
-          merge_table_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
-        elsif 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)
+          # Emit table header and merge children
+          @emitter.emit_table_header(dest_node.table_name || template_node.table_name)
+
+          template_children = template_node.children
+          dest_children = dest_node.children
+
+          merge_node_lists_to_emitter(
+            template_children,
+            dest_children,
+            template_analysis,
+            dest_analysis,
+          )
         elsif @preference == :destination
           # Leaf nodes or mismatched types - use preference
-          add_node_to_result(dest_node, result, :destination, MergeResult::DECISION_KEPT_DEST, dest_analysis)
+          emit_node(dest_node, dest_analysis)
         else
-          add_node_to_result(template_node, result, :template, MergeResult::DECISION_KEPT_TEMPLATE, template_analysis)
+          emit_node(template_node, template_analysis)
+        end
+      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)
+        # Emit the node content
+        if node.start_line && node.end_line
+          lines = []
+          (node.start_line..node.end_line).each do |line_num|
+            line = analysis.line_at(line_num)
+            lines << line if line
+          end
+          @emitter.emit_raw_lines(lines)
         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.
+      # Build a map of refined matches
       # @param template_nodes [Array<NodeWrapper>] Template nodes
       # @param dest_nodes [Array<NodeWrapper>] Destination nodes
       # @param template_by_sig [Hash] Template signature map
@@ -189,76 +212,6 @@ module Toml
           h[match.template_node] = match.dest_node
         end
       end
-
-      # Merge two table nodes by emitting the table header and recursively merging pairs
-      # @param template_node [NodeWrapper] Template table node
-      # @param dest_node [NodeWrapper] Destination table node
-      # @param template_analysis [FileAnalysis] Template analysis
-      # @param dest_analysis [FileAnalysis] Destination analysis
-      # @param result [MergeResult] Result to populate
-      def merge_table_nodes(template_node, dest_node, template_analysis, dest_analysis, result)
-        # Use destination's table header line
-        header = dest_node.opening_line || template_node.opening_line
-        result.add_line(header, decision: MergeResult::DECISION_MERGED, source: :merged) if header
-
-        # Recursively merge the pairs within the table
-        template_pairs = template_node.pairs
-        dest_pairs = dest_node.pairs
-
-        merge_node_lists(
-          template_pairs,
-          dest_pairs,
-          template_analysis,
-          dest_analysis,
-          result,
-        )
-      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)
-        # 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,
-        )
-      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 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/toml/merge/emitter.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Toml
+  module Merge
+    # Custom TOML emitter that preserves comments and formatting.
+    # This class provides utilities for emitting TOML 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_table_header("section")
+    #   emitter.emit_key_value("key", "value")
+    class Emitter < Ast::Merge::EmitterBase
+      # Initialize subclass-specific state
+      def initialize_subclass_state(**options)
+        # TOML doesn't need separator tracking like JSON
+      end
+
+      # Clear subclass-specific state
+      def clear_subclass_state
+        # Nothing to clear for TOML
+      end
+
+      # Emit a tracked comment from CommentTracker
+      # @param comment [Hash] Comment with :text, :indent
+      def emit_tracked_comment(comment)
+        indent = " " * (comment[:indent] || 0)
+        @lines << "#{indent}# #{comment[:text]}"
+      end
+
+      # Emit a comment line
+      #
+      # @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 table header
+      #
+      # @param name [String] Table name (e.g., "package" or "dependencies.dev")
+      def emit_table_header(name)
+        @lines << "[#{name}]"
+      end
+
+      # Emit an array of tables header
+      #
+      # @param name [String] Array of tables name
+      def emit_array_of_tables_header(name)
+        @lines << "[[#{name}]]"
+      end
+
+      # Emit a key-value pair
+      #
+      # @param key [String] Key name
+      # @param value [String] Value (already formatted as TOML)
+      # @param inline_comment [String, nil] Optional inline comment
+      def emit_key_value(key, value, inline_comment: nil)
+        line = "#{current_indent}#{key} = #{value}"
+        line += " # #{inline_comment}" if inline_comment
+        @lines << line
+      end
+
+      # Emit an inline table
+      #
+      # @param key [String] Key name
+      # @param pairs [Hash] Key-value pairs for the inline table
+      def emit_inline_table(key, pairs)
+        formatted_pairs = pairs.map { |k, v| "#{k} = #{v}" }.join(", ")
+        @lines << "#{current_indent}#{key} = { #{formatted_pairs} }"
+      end
+
+      # Emit an inline array
+      #
+      # @param key [String] Key name
+      # @param items [Array] Array items (already formatted)
+      def emit_inline_array(key, items)
+        formatted_items = items.join(", ")
+        @lines << "#{current_indent}#{key} = [#{formatted_items}]"
+      end
+
+      # Emit a multi-line array start
+      #
+      # @param key [String] Key name
+      def emit_array_start(key)
+        @lines << "#{current_indent}#{key} = ["
+        indent
+      end
+
+      # Emit an array item
+      #
+      # @param value [String] Item value (already formatted)
+      def emit_array_item(value)
+        @lines << "#{current_indent}#{value},"
+      end
+
+      # Emit an array end
+      def emit_array_end
+        dedent
+        @lines << "#{current_indent}]"
+      end
+
+      # Get the output as a TOML string
+      #
+      # @return [String]
+      def to_toml
+        to_s
+      end
+    end
+  end
+end

data/lib/toml/merge/file_analysis.rb

@@ -18,15 +18,36 @@ module Toml
       # @return [Array] Parse errors if any
       attr_reader :errors
 
+      # @return [Symbol] The backend used for parsing (:tree_sitter or :citrus)
+      attr_reader :backend
+
+      class << self
+        # Find the parser library path using TreeHaver::GrammarFinder
+        #
+        # @return [String, nil] Path to the parser library or nil if not found
+        def find_parser_path
+          TreeHaver::GrammarFinder.new(:toml).find_library_path
+        end
+      end
+
       # Initialize file analysis
       #
       # @param source [String] TOML source code to analyze
+      # @param source [String] TOML source code to analyze
       # @param signature_generator [Proc, nil] Custom signature generator
-      def initialize(source, signature_generator: nil)
+      # @param parser_path [String, nil] Path to tree-sitter-toml parser library
+      # @param options [Hash] Additional options (forward compatibility - freeze_token, node_typing, etc.)
+      #
+      # @note To force a specific backend, use TreeHaver.with_backend or TREE_HAVER_BACKEND env var.
+      #   TreeHaver handles backend selection, auto-detection, and fallback.
+      def initialize(source, signature_generator: nil, parser_path: nil, **options)
         @source = source
         @lines = source.lines.map(&:chomp)
         @signature_generator = signature_generator
+        @parser_path = parser_path || self.class.find_parser_path
         @errors = []
+        @backend = :tree_sitter  # Default, will be updated during parsing
+        # **options captures any additional parameters (e.g., freeze_token, node_typing) for forward compatibility
 
         # Parse the TOML
         DebugLogger.time("FileAnalysis#parse_toml") { parse_toml }
@@ -58,7 +79,14 @@ module Toml
       def root_node
         return unless valid?
 
-        NodeWrapper.new(@ast.root_node, lines: @lines, source: @source)
+        root = @ast.root_node
+        NodeWrapper.new(
+          root,
+          lines: @lines,
+          source: @source,
+          backend: @backend,
+          document_root: root,
+        )
       end
 
       # Get a hash mapping signatures to nodes
@@ -68,30 +96,73 @@ module Toml
       end
 
       # Get all top-level tables (sections) in the TOML document
+      # Uses NodeTypeNormalizer for backend-agnostic type checking.
+      # Passes document_root to enable Citrus backend normalization (pairs as siblings).
       # @return [Array<NodeWrapper>]
       def tables
         return [] unless valid?
 
         result = []
-        @ast.root_node.each do |child|
-          child_type = child.type.to_s
-          next unless %w[table array_of_tables].include?(child_type)
-
-          result << NodeWrapper.new(child, lines: @lines, source: @source)
+        root = @ast.root_node
+        root.each do |child|
+          canonical_type = NodeTypeNormalizer.canonical_type(child.type, @backend)
+          next unless NodeTypeNormalizer.table_type?(canonical_type)
+
+          result << NodeWrapper.new(
+            child,
+            lines: @lines,
+            source: @source,
+            backend: @backend,
+            document_root: root,
+          )
         end
         result
       end
 
       # Get all top-level key-value pairs (not in tables)
+      #
+      # For tree-sitter backend: pairs are nested under tables, so root-level
+      # pairs are direct children of the document.
+      #
+      # For Citrus backend: ALL pairs are siblings at document level (flat structure).
+      # We must filter to only include pairs that appear BEFORE the first table header.
+      #
       # @return [Array<NodeWrapper>]
       def root_pairs
         return [] unless valid?
 
         result = []
-        @ast.root_node.each do |child|
-          next unless child.type.to_s == "pair"
+        root = @ast.root_node
 
-          result << NodeWrapper.new(child, lines: @lines, source: @source)
+        # Find the line number of the first table (if any)
+        first_table_line = nil
+        root.each do |child|
+          canonical_type = NodeTypeNormalizer.canonical_type(child.type, @backend)
+          if NodeTypeNormalizer.table_type?(canonical_type)
+            child_line = child.respond_to?(:start_point) ? child.start_point.row + 1 : nil
+            if child_line && (first_table_line.nil? || child_line < first_table_line)
+              first_table_line = child_line
+            end
+          end
+        end
+
+        root.each do |child|
+          canonical_type = NodeTypeNormalizer.canonical_type(child.type, @backend)
+          next unless canonical_type == :pair
+
+          # For Citrus backend, only include pairs before the first table
+          if first_table_line
+            child_line = child.respond_to?(:start_point) ? child.start_point.row + 1 : nil
+            next if child_line && child_line >= first_table_line
+          end
+
+          result << NodeWrapper.new(
+            child,
+            lines: @lines,
+            source: @source,
+            backend: @backend,
+            document_root: root,
+          )
         end
         result
       end
@@ -99,33 +170,37 @@ module Toml
       private
 
       def parse_toml
-        # Check if TreeHaver is available
-        unless defined?(TreeHaver)
-          error_msg = "TreeHaver not available. Install tree_haver gem."
-          @errors << error_msg
-          @ast = nil
-          raise StandardError, error_msg
-        end
-
-        begin
-          # Use TreeHaver's unified interface
-          # TreeHaver automatically handles backend selection and Citrus fallback
-          # when tree-sitter-toml is not available
-          parser = TreeHaver::Parser.new
-          parser.language = TreeHaver::Language.toml
-          @ast = parser.parse(@source)
-
-          # Check for parse errors in the tree
-          if @ast&.root_node&.has_error?
-            collect_parse_errors(@ast.root_node)
-            # Raise to allow SmartMergerBase to wrap with appropriate error type
-            raise StandardError, "TOML parse error: #{@errors.first}"
-          end
-        rescue StandardError => e
-          @errors << e unless @errors.include?(e)
-          @ast = nil
-          raise
+        # TreeHaver handles everything:
+        # - Backend selection (via TREE_HAVER_BACKEND env or TreeHaver.backend)
+        # - Grammar auto-discovery
+        # - Fallback to Citrus if tree-sitter unavailable
+        # - CITRUS_DEFAULTS already includes toml configuration
+        parser_options = {}
+        parser_options[:library_path] = @parser_path if @parser_path
+
+        parser = TreeHaver.parser_for(:toml, **parser_options)
+
+        # For NodeTypeNormalizer, we only care: is it Citrus or tree-sitter format?
+        # All native backends (mri, rust, ffi, java) produce tree-sitter AST format.
+        @backend = (parser.backend == :citrus) ? :citrus : :tree_sitter
+
+        @ast = parser.parse(@source)
+
+        # Check for parse errors in the tree
+        if @ast&.root_node&.has_error?
+          collect_parse_errors(@ast.root_node)
+          # Don't raise here - let SmartMergerBase detect via valid? check
+          # This is consistent with how other FileAnalysis classes handle parse errors
         end
+      rescue TreeHaver::Error => e
+        # TreeHaver::Error inherits from Exception, not StandardError.
+        # This also catches TreeHaver::NotAvailable (subclass of Error).
+        # Catch parse errors from Citrus backend and other TreeHaver errors.
+        @errors << e.message
+        @ast = nil
+      rescue StandardError => e
+        @errors << e unless @errors.include?(e)
+        @ast = nil
       end
 
       def collect_parse_errors(node)
@@ -151,11 +226,19 @@ module Toml
 
         # Return all root-level nodes (document children)
         # For TOML, this includes tables, array_of_tables, and top-level pairs
+        # Pass document_root to enable Citrus backend normalization (pairs as siblings)
         root.each do |child|
           # Skip comments (handled separately)
-          next if child.type.to_s == "comment"
-
-          wrapper = NodeWrapper.new(child, lines: @lines, source: @source)
+          canonical_type = NodeTypeNormalizer.canonical_type(child.type, @backend)
+          next if canonical_type == :comment
+
+          wrapper = NodeWrapper.new(
+            child,
+            lines: @lines,
+            source: @source,
+            backend: @backend,
+            document_root: root,
+          )
           next unless wrapper.start_line && wrapper.end_line
 
           result << wrapper

data/lib/toml/merge/merge_result.rb

@@ -22,8 +22,9 @@ module Toml
       attr_reader :statistics
 
       # Initialize a new merge result
-      def initialize
-        super
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(**options)
+        super(**options)
         @statistics = {
           template_lines: 0,
           dest_lines: 0,
@@ -78,9 +79,14 @@ module Toml
       # @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
+        return unless node.start_line
 
-        (node.start_line..node.end_line).each do |line_num|
+        # Use effective_end_line for tables to include associated pairs on Citrus backend
+        # (Citrus has flat structure where pairs are siblings, not children of tables)
+        end_line = node.respond_to?(:effective_end_line) ? node.effective_end_line : node.end_line
+        return unless end_line
+
+        (node.start_line..end_line).each do |line_num|
           line = analysis.line_at(line_num)
           next unless line