ast-merge 1.0.0

data/lib/ast/merge/smart_merger_base.rb

@@ -0,0 +1,417 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Abstract base class for SmartMerger implementations across all *-merge gems.
+    #
+    # SmartMergerBase provides the standard interface and common functionality
+    # for intelligent file merging. Subclasses implement format-specific parsing,
+    # analysis, and merge logic while inheriting the common API.
+    #
+    # ## Standard Options
+    #
+    # All SmartMerger implementations support these common options:
+    #
+    # - `preference` - `:destination` (default) or `:template`
+    # - `add_template_only_nodes` - `false` (default) or `true`
+    # - `signature_generator` - Custom signature proc or `nil`
+    # - `freeze_token` - Token for freeze block markers
+    # - `match_refiner` - Fuzzy match refiner or `nil`
+    # - `regions` - Region configurations for nested merging
+    # - `region_placeholder` - Custom placeholder for regions
+    #
+    # ## Implementing a SmartMerger
+    #
+    # Subclasses must implement:
+    # - `analysis_class` - Returns the FileAnalysis class for this format
+    # - `perform_merge` - Performs the format-specific merge logic
+    #
+    # Subclasses may override:
+    # - `default_freeze_token` - Format-specific default freeze token
+    # - `resolver_class` - Returns the ConflictResolver class (if different)
+    # - `result_class` - Returns the MergeResult class (if different)
+    # - `aligner_class` - Returns the FileAligner class (if used)
+    # - `parse_content` - Custom parsing logic
+    # - `build_analysis_options` - Additional analysis options
+    # - `build_resolver_options` - Additional resolver options
+    #
+    # @example Implementing a custom SmartMerger
+    #   class MyFormat::SmartMerger < Ast::Merge::SmartMergerBase
+    #     def analysis_class
+    #       MyFormat::FileAnalysis
+    #     end
+    #
+    #     def default_freeze_token
+    #       "myformat-merge"
+    #     end
+    #
+    #     private
+    #
+    #     def perform_merge
+    #       alignment = @aligner.align
+    #       process_alignment(alignment)
+    #       @result
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement {#analysis_class} and {#perform_merge}
+    # @api public
+    class SmartMergerBase
+      include RegionMergeable
+
+      # @return [String] Template source content
+      attr_reader :template_content
+
+      # @return [String] Destination source content
+      attr_reader :dest_content
+
+      # @return [Object] Analysis of the template file
+      attr_reader :template_analysis
+
+      # @return [Object] Analysis of the destination file
+      attr_reader :dest_analysis
+
+      # @return [Object, nil] Aligner for finding matches (if applicable)
+      attr_reader :aligner
+
+      # @return [Object] Resolver for handling conflicts
+      attr_reader :resolver
+
+      # @return [Object] Result object tracking merged content
+      attr_reader :result
+
+      # @return [Symbol, Hash] Preference for signature matches
+      attr_reader :preference
+
+      # @return [Boolean] Whether to add template-only nodes
+      attr_reader :add_template_only_nodes
+
+      # @return [String] Token for freeze block markers
+      attr_reader :freeze_token
+
+      # @return [Proc, nil] Custom signature generator
+      attr_reader :signature_generator
+
+      # @return [Object, nil] Match refiner for fuzzy matching
+      attr_reader :match_refiner
+
+      # Creates a new SmartMerger for intelligent file merging.
+      #
+      # @param template_content [String] Template source content
+      # @param dest_content [String] Destination source content
+      #
+      # @param signature_generator [Proc, nil] Optional proc to generate custom signatures.
+      #   The proc receives a node and should return one of:
+      #   - An array representing the node's signature
+      #   - `nil` to indicate the node should have no signature
+      #   - The original node to fall through to default signature computation
+      #
+      # @param preference [Symbol, Hash] Controls which version to use
+      #   when nodes have matching signatures but different content:
+      #   - `:destination` (default) - Use destination version (preserves customizations)
+      #   - `:template` - Use template version (applies updates)
+      #   - Hash for per-type preferences: `{ default: :destination, special: :template }`
+      #
+      # @param add_template_only_nodes [Boolean] Controls whether to add nodes that only
+      #   exist in template:
+      #   - `false` (default) - Skip template-only nodes
+      #   - `true` - Add template-only nodes to result
+      #
+      # @param freeze_token [String, nil] Token to use for freeze block markers.
+      #   Default varies by format (e.g., "prism-merge", "markly-merge")
+      #
+      # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching.
+      #   Default: nil (fuzzy matching disabled)
+      #
+      # @param regions [Array<Hash>, nil] Region configurations for nested merging.
+      #   Each hash should contain:
+      #   - `:detector` - RegionDetectorBase instance
+      #   - `:merger_class` - SmartMerger class for the region (optional)
+      #   - `:merger_options` - Options for the region merger (optional)
+      #   - `:regions` - Nested region configs (optional, for recursive regions)
+      #
+      # @param region_placeholder [String, nil] Custom placeholder prefix for regions.
+      #   Default: "<<<AST_MERGE_REGION_"
+      #
+      # @param format_options [Hash] Format-specific parser options passed to FileAnalysis.
+      #   These are merged with freeze_token and signature_generator in build_full_analysis_options.
+      #   Examples:
+      #   - Markly: `flags: Markly::FOOTNOTES, extensions: [:table, :strikethrough]`
+      #   - Commonmarker: `options: { parse: { smart: true } }`
+      #   - Prism: (no additional parser options needed)
+      #
+      # @raise [Ast::Merge::TemplateParseError] If template has syntax errors
+      # @raise [Ast::Merge::DestinationParseError] If destination has syntax errors
+      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,
+        **format_options
+      )
+        @template_content = template_content
+        @dest_content = dest_content
+        @signature_generator = signature_generator
+        @preference = preference
+        @add_template_only_nodes = add_template_only_nodes
+        @freeze_token = freeze_token || default_freeze_token
+        @match_refiner = match_refiner
+        @format_options = format_options
+
+        # Set up region support
+        setup_regions(regions: regions || [], region_placeholder: region_placeholder)
+
+        # Extract regions before parsing (if configured)
+        template_for_parsing = extract_template_regions(@template_content)
+        dest_for_parsing = extract_dest_regions(@dest_content)
+
+        # Parse and analyze both files
+        @template_analysis = parse_and_analyze(template_for_parsing, :template)
+        @dest_analysis = parse_and_analyze(dest_for_parsing, :destination)
+
+        # Set up aligner (if applicable)
+        @aligner = build_aligner if respond_to?(:aligner_class, true) && aligner_class
+
+        # Set up resolver
+        @resolver = build_resolver
+
+        # Set up result
+        @result = build_result
+      end
+
+      # Perform the merge operation and return the merged content as a string.
+      #
+      # @return [String] The merged content
+      def merge
+        merge_result.to_s
+      end
+
+      # Perform the merge operation and return the full result object.
+      #
+      # This method is memoized - subsequent calls return the cached result.
+      #
+      # @return [Object] The merge result (format-specific MergeResult subclass)
+      def merge_result
+        return @merge_result if @merge_result
+
+        @merge_result = DebugLogger.time("#{self.class.name}#merge") do
+          result = perform_merge
+
+          # Substitute merged regions back into the result if configured
+          if regions_configured? && (merged_content = result.to_s)
+            final_content = substitute_merged_regions(merged_content)
+            update_result_content(result, final_content)
+          end
+
+          result
+        end
+      end
+
+      # Perform the merge and return detailed debug information.
+      #
+      # @return [Hash] Hash containing:
+      #   - `:content` [String] - Final merged content
+      #   - `:statistics` [Hash] - Merge decision counts
+      def merge_with_debug
+        content = merge
+
+        {
+          content: content,
+          statistics: @result.decision_summary,
+        }
+      end
+
+      # Get merge statistics.
+      #
+      # @return [Hash] Statistics about the merge
+      def stats
+        merge_result # Ensure merge has run
+        @result.decision_summary
+      end
+
+      protected
+
+      # Returns the FileAnalysis class for this format.
+      #
+      # @return [Class] The analysis class
+      # @abstract Subclasses must implement this method
+      def analysis_class
+        raise NotImplementedError, "#{self.class}#analysis_class must be implemented"
+      end
+
+      # Returns the default freeze token for this format.
+      #
+      # @return [String] The default freeze token (e.g., "prism-merge")
+      def default_freeze_token
+        "ast-merge"
+      end
+
+      # Returns the ConflictResolver class for this format.
+      #
+      # Override if your format uses a custom resolver.
+      #
+      # @return [Class, nil] The resolver class, or nil to skip resolver creation
+      def resolver_class
+        nil
+      end
+
+      # Returns the MergeResult class for this format.
+      #
+      # Override if your format uses a custom result class.
+      #
+      # @return [Class, nil] The result class, or nil to skip result creation
+      def result_class
+        nil
+      end
+
+      # Returns the FileAligner class for this format.
+      #
+      # Override if your format uses an aligner.
+      #
+      # @return [Class, nil] The aligner class, or nil if not used
+      def aligner_class
+        nil
+      end
+
+      # Performs the format-specific merge logic.
+      #
+      # This method should use @template_analysis, @dest_analysis, @resolver, etc.
+      # to perform the merge and populate @result.
+      #
+      # @return [Object] The merge result (typically @result)
+      # @abstract Subclasses must implement this method
+      def perform_merge
+        raise NotImplementedError, "#{self.class}#perform_merge must be implemented"
+      end
+
+      # Build additional options for FileAnalysis.
+      #
+      # Override to add format-specific options.
+      #
+      # @return [Hash] Additional options for the analysis class
+      def build_analysis_options
+        {}
+      end
+
+      # Build additional options for ConflictResolver.
+      #
+      # Override to add format-specific options.
+      #
+      # @return [Hash] Additional options for the resolver class
+      def build_resolver_options
+        {}
+      end
+
+      # Update the result content after region substitution.
+      #
+      # Override if your result class needs special handling.
+      #
+      # @param result [Object] The merge result
+      # @param content [String] The final content with regions substituted
+      def update_result_content(result, content)
+        result.content = content
+      end
+
+      private
+
+      # Parse and analyze content, raising appropriate errors.
+      #
+      # @param content [String] Content to parse
+      # @param source [Symbol] :template or :destination
+      # @return [Object] The analysis result
+      def parse_and_analyze(content, source)
+        options = build_full_analysis_options
+
+        DebugLogger.time("#{self.class.name}#analyze_#{source}") do
+          analysis_class.new(content, **options)
+        end
+      rescue StandardError => e
+        # Don't re-wrap our own parse errors
+        raise if e.is_a?(template_parse_error_class) || e.is_a?(destination_parse_error_class)
+
+        error_class = (source == :template) ? template_parse_error_class : destination_parse_error_class
+        raise error_class.new(errors: [e], content: content)
+      end
+
+      # Returns the TemplateParseError class for this merger.
+      # Override in subclasses to use format-specific error classes.
+      #
+      # @return [Class] The template parse error class
+      def template_parse_error_class
+        TemplateParseError
+      end
+
+      # Returns the DestinationParseError class for this merger.
+      # Override in subclasses to use format-specific error classes.
+      #
+      # @return [Class] The destination parse error class
+      def destination_parse_error_class
+        DestinationParseError
+      end
+
+      # Build the complete options hash for FileAnalysis.
+      #
+      # Override this method to completely control what options are passed.
+      # By default, includes freeze_token, signature_generator, and format_options.
+      #
+      # @return [Hash] Options for the analysis class
+      def build_full_analysis_options
+        {
+          freeze_token: @freeze_token,
+          signature_generator: @signature_generator,
+        }.merge(build_analysis_options).merge(@format_options)
+      end
+
+      # Build the aligner instance.
+      #
+      # Override if your aligner has a different constructor signature.
+      #
+      # @return [Object] The aligner instance
+      def build_aligner
+        aligner_class.new(@template_analysis, @dest_analysis, match_refiner: @match_refiner)
+      end
+
+      # Build the resolver instance.
+      #
+      # Override if your resolver has a different constructor signature.
+      #
+      # @return [Object, nil] The resolver instance
+      def build_resolver
+        return unless resolver_class
+
+        options = {
+          preference: @preference,
+          template_analysis: @template_analysis,
+          dest_analysis: @dest_analysis,
+          add_template_only_nodes: @add_template_only_nodes,
+          match_refiner: @match_refiner,
+        }.merge(build_resolver_options)
+
+        resolver_class.new(**options)
+      end
+
+      # Build the result instance.
+      #
+      # Override if your result class has a different constructor signature.
+      #
+      # @return [Object, nil] The result instance
+      def build_result
+        return unless result_class
+
+        if result_class.instance_method(:initialize).arity == 0
+          result_class.new
+        else
+          result_class.new(
+            template_analysis: @template_analysis,
+            dest_analysis: @dest_analysis,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/text/conflict_resolver.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Text
+      # Conflict resolver for text-based AST merging.
+      #
+      # Uses content-based matching with destination-order preservation:
+      # 1. Lines are matched by normalized content (whitespace-trimmed)
+      # 2. Destination order is preserved (destination is source of truth for structure)
+      # 3. Template-only lines are optionally added at the end
+      # 4. Freeze blocks are always preserved from destination
+      #
+      # @example
+      #   resolver = ConflictResolver.new(template_analysis, dest_analysis)
+      #   result = MergeResult.new
+      #   resolver.resolve(result)
+      class ConflictResolver < ConflictResolverBase
+        # Initialize the conflict resolver
+        #
+        # @param template_analysis [FileAnalysis] Analysis of template
+        # @param dest_analysis [FileAnalysis] Analysis of destination
+        # @param preference [Symbol] :destination or :template
+        # @param add_template_only_nodes [Boolean] Whether to add template-only lines
+        def initialize(
+          template_analysis,
+          dest_analysis,
+          preference: :destination,
+          add_template_only_nodes: false
+        )
+          super(
+            strategy: :batch,
+            preference: preference,
+            template_analysis: template_analysis,
+            dest_analysis: dest_analysis,
+            add_template_only_nodes: add_template_only_nodes
+          )
+        end
+
+        protected
+
+        # Resolve using content-based matching with destination order preservation
+        #
+        # @param result [MergeResult] Result object to populate
+        # @return [void]
+        def resolve_batch(result)
+          template_statements = @template_analysis.statements
+          dest_statements = @dest_analysis.statements
+
+          # Build content index for matching
+          template_by_content = build_content_index(template_statements)
+
+          # Track matched template indices
+          matched_template_indices = Set.new
+
+          # Process destination in order - destination structure is preserved
+          dest_statements.each do |dest_node|
+            if freeze_node?(dest_node)
+              # Freeze blocks are always preserved from destination
+              add_freeze_block(result, dest_node)
+              next
+            end
+
+            # Find matching template line by normalized content
+            normalized = dest_node.normalized_content
+            template_match = find_unmatched(template_by_content[normalized], matched_template_indices)
+
+            if template_match
+              matched_template_indices << template_match[:index]
+              resolve_matched_pair(result, template_match[:node], dest_node)
+            else
+              # Destination-only content - always preserve
+              result.add_line(dest_node.content)
+              result.record_decision(DECISION_APPENDED, nil, dest_node)
+            end
+          end
+
+          # Add template-only lines if configured
+          if @add_template_only_nodes
+            add_unmatched_template_lines(result, template_statements, matched_template_indices)
+          end
+        end
+
+        private
+
+        # Build an index of statements by normalized content
+        #
+        # @param statements [Array] Statements to index
+        # @return [Hash] Map of normalized content => [{node:, index:}, ...]
+        def build_content_index(statements)
+          index = Hash.new { |h, k| h[k] = [] }
+          statements.each_with_index do |node, idx|
+            next if freeze_node?(node)
+
+            normalized = node.normalized_content
+            index[normalized] << {node: node, index: idx}
+          end
+          index
+        end
+
+        # Find first unmatched entry from a list
+        #
+        # @param entries [Array, nil] List of {node:, index:} hashes
+        # @param matched_indices [Set] Already matched indices
+        # @return [Hash, nil] First unmatched entry or nil
+        def find_unmatched(entries, matched_indices)
+          return unless entries
+
+          entries.find { |e| !matched_indices.include?(e[:index]) }
+        end
+
+        # Add a freeze block to the result
+        #
+        # @param result [MergeResult] Result to populate
+        # @param freeze_node [FreezeNodeBase] Freeze block node
+        def add_freeze_block(result, freeze_node)
+          freeze_node.content.split("\n").each do |line|
+            result.add_line(line)
+          end
+          result.record_decision(DECISION_FROZEN, nil, freeze_node)
+        end
+
+        # Add unmatched template lines in their original order
+        #
+        # @param result [MergeResult] Result to populate
+        # @param template_statements [Array] All template statements
+        # @param matched_indices [Set] Indices of matched template nodes
+        def add_unmatched_template_lines(result, template_statements, matched_indices)
+          template_statements.each_with_index do |template_node, idx|
+            next if matched_indices.include?(idx)
+            next if freeze_node?(template_node)
+
+            result.add_line(template_node.content)
+            result.record_decision(DECISION_ADDED, template_node, nil)
+          end
+        end
+
+        # Resolve a matched pair of nodes
+        #
+        # @param result [MergeResult] Result to populate
+        # @param template_node [LineNode] Template node
+        # @param dest_node [LineNode] Destination node
+        def resolve_matched_pair(result, template_node, dest_node)
+          if template_node.content == dest_node.content
+            # Identical content
+            result.add_line(dest_node.content)
+            result.record_decision(DECISION_IDENTICAL, template_node, dest_node)
+          elsif @preference == :template
+            # Template wins - use template content
+            result.add_line(template_node.content)
+            result.record_decision(DECISION_KEPT_TEMPLATE, template_node, dest_node)
+          else
+            # Destination wins (default) - use destination content
+            result.add_line(dest_node.content)
+            result.record_decision(DECISION_KEPT_DEST, template_node, dest_node)
+          end
+        end
+      end
+    end
+  end
+end