ast-merge 1.0.0

data/lib/ast/merge/conflict_resolver_base.rb

@@ -0,0 +1,399 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for conflict resolvers across all *-merge gems.
+    #
+    # Provides common functionality for resolving conflicts between template
+    # and destination content during merge operations. Supports three resolution
+    # strategies that can be selected based on the needs of each file format:
+    #
+    # - `:node` - Per-node resolution (resolve individual node pairs)
+    # - `:batch` - Batch resolution (resolve entire file using signature maps)
+    # - `:boundary` - Boundary resolution (resolve sections/ranges of content)
+    #
+    # @example Node-based resolution (commonmarker-merge style)
+    #   class ConflictResolver < Ast::Merge::ConflictResolverBase
+    #     def initialize(preference:, template_analysis:, dest_analysis:)
+    #       super(
+    #         strategy: :node,
+    #         preference: preference,
+    #         template_analysis: template_analysis,
+    #         dest_analysis: dest_analysis
+    #       )
+    #     end
+    #
+    #     # Called for each node pair
+    #     def resolve_node_pair(template_node, dest_node, template_index:, dest_index:)
+    #       # Return resolution hash
+    #     end
+    #   end
+    #
+    # @example Batch resolution (psych-merge/json-merge style)
+    #   class ConflictResolver < Ast::Merge::ConflictResolverBase
+    #     def initialize(template_analysis, dest_analysis, preference: :destination)
+    #       super(
+    #         strategy: :batch,
+    #         preference: preference,
+    #         template_analysis: template_analysis,
+    #         dest_analysis: dest_analysis
+    #       )
+    #     end
+    #
+    #     # Called once for entire merge
+    #     def resolve_batch(result)
+    #       # Populate result with merged content
+    #     end
+    #   end
+    #
+    # @example Boundary resolution (prism-merge style)
+    #   class ConflictResolver < Ast::Merge::ConflictResolverBase
+    #     def initialize(template_analysis, dest_analysis, preference: :destination)
+    #       super(
+    #         strategy: :boundary,
+    #         preference: preference,
+    #         template_analysis: template_analysis,
+    #         dest_analysis: dest_analysis
+    #       )
+    #     end
+    #
+    #     # Called for each boundary (section with differences)
+    #     def resolve_boundary(boundary, result)
+    #       # Process boundary and populate result
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement resolve_node_pair, resolve_batch, or resolve_boundary
+    class ConflictResolverBase
+      # Decision constants - shared across all conflict resolvers
+
+      # Use destination version (customization preserved)
+      DECISION_DESTINATION = :destination
+
+      # Use template version (update applied)
+      DECISION_TEMPLATE = :template
+
+      # Content was added from template (template-only)
+      DECISION_ADDED = :added
+
+      # Content preserved from frozen block
+      DECISION_FROZEN = :frozen
+
+      # Content was identical (no conflict)
+      DECISION_IDENTICAL = :identical
+
+      # Content was kept from destination (signature match, dest preferred)
+      DECISION_KEPT_DEST = :kept_destination
+
+      # Content was kept from template (signature match, template preferred)
+      DECISION_KEPT_TEMPLATE = :kept_template
+
+      # Content was appended from destination (dest-only)
+      DECISION_APPENDED = :appended
+
+      # Content preserved from freeze block marker
+      DECISION_FREEZE_BLOCK = :freeze_block
+
+      # Content requires recursive merge (container types)
+      DECISION_RECURSIVE = :recursive
+
+      # Content was replaced (signature match with different content)
+      DECISION_REPLACED = :replaced
+
+      # @return [Symbol] Resolution strategy (:node, :batch, or :boundary)
+      attr_reader :strategy
+
+      # @return [Symbol, Hash] Merge preference.
+      #   As Symbol: :destination or :template (applies to all nodes)
+      #   As Hash: Maps node types/merge_types to preferences
+      #     @example { default: :destination, lint_gem: :template }
+      attr_reader :preference
+
+      # @return [Object] Template file analysis
+      attr_reader :template_analysis
+
+      # @return [Object] Destination file analysis
+      attr_reader :dest_analysis
+
+      # @return [Boolean] Whether to add template-only nodes (batch strategy)
+      attr_reader :add_template_only_nodes
+
+      # Initialize the conflict resolver
+      #
+      # @param strategy [Symbol] Resolution strategy (:node, :batch, or :boundary)
+      # @param preference [Symbol, Hash] Which version to prefer.
+      #   As Symbol: :destination or :template (applies to all nodes)
+      #   As Hash: Maps node types/merge_types to preferences
+      #     - Use :default key for fallback preference
+      #     @example { default: :destination, lint_gem: :template }
+      # @param template_analysis [Object] Analysis of the template file
+      # @param dest_analysis [Object] Analysis of the destination file
+      # @param add_template_only_nodes [Boolean] Whether to add nodes only in template (batch/boundary strategy)
+      def initialize(strategy:, preference:, template_analysis:, dest_analysis:, add_template_only_nodes: false)
+        unless %i[node batch boundary].include?(strategy)
+          raise ArgumentError, "Invalid strategy: #{strategy}. Must be :node, :batch, or :boundary"
+        end
+
+        validate_preference!(preference)
+
+        @strategy = strategy
+        @preference = preference
+        @template_analysis = template_analysis
+        @dest_analysis = dest_analysis
+        @add_template_only_nodes = add_template_only_nodes
+      end
+
+      # Resolve conflicts using the configured strategy
+      #
+      # For :node strategy, this delegates to resolve_node_pair
+      # For :batch strategy, this delegates to resolve_batch
+      # For :boundary strategy, this delegates to resolve_boundary
+      #
+      # @param args [Array] Arguments passed to the strategy method
+      # @return [Object] Resolution result (format depends on strategy)
+      def resolve(*args, **kwargs)
+        case @strategy
+        when :node
+          resolve_node_pair(*args, **kwargs)
+        when :batch
+          resolve_batch(*args)
+        when :boundary
+          resolve_boundary(*args)
+        end
+      end
+
+      # Check if a node is a freeze node using duck typing
+      #
+      # @param node [Object] Node to check
+      # @return [Boolean] True if node is a freeze node
+      def freeze_node?(node)
+        node.respond_to?(:freeze_node?) && node.freeze_node?
+      end
+
+      # Get the preference for a specific node.
+      #
+      # When preference is a Hash, looks up the preference for the node's
+      # merge_type (if wrapped with NodeTyping) or falls back to :default.
+      #
+      # @param node [Object, nil] The node to get preference for
+      # @return [Symbol] :destination or :template
+      #
+      # @example With Symbol preference
+      #   preference_for_node(any_node)  # => returns @preference
+      #
+      # @example With Hash preference and typed node
+      #   # Given preference: { default: :destination, lint_gem: :template }
+      #   preference_for_node(lint_gem_node)  # => :template
+      #   preference_for_node(other_node)     # => :destination
+      def preference_for_node(node)
+        return default_preference unless @preference.is_a?(Hash)
+        return default_preference unless node
+
+        # Check if node has a merge_type (from NodeTyping)
+        merge_type = NodeTyping.merge_type_for(node)
+        return @preference.fetch(merge_type) { default_preference } if merge_type
+
+        # Fall back to default
+        default_preference
+      end
+
+      # Get the default preference (used as fallback).
+      #
+      # @return [Symbol] :destination or :template
+      def default_preference
+        if @preference.is_a?(Hash)
+          @preference.fetch(:default, :destination)
+        else
+          @preference
+        end
+      end
+
+      # Check if Hash-based per-type preferences are configured.
+      #
+      # @return [Boolean] true if preference is a Hash
+      def per_type_preference?
+        @preference.is_a?(Hash)
+      end
+
+      protected
+
+      # Resolve a single node pair (for :node strategy)
+      # Override this method in subclasses using node strategy
+      #
+      # @param template_node [Object] Node from template
+      # @param dest_node [Object] Node from destination
+      # @param template_index [Integer] Index in template statements
+      # @param dest_index [Integer] Index in destination statements
+      # @return [Hash] Resolution with :source, :decision, and node references
+      def resolve_node_pair(template_node, dest_node, template_index:, dest_index:)
+        raise NotImplementedError, "Subclass must implement resolve_node_pair for :node strategy"
+      end
+
+      # Resolve all conflicts in batch (for :batch strategy)
+      # Override this method in subclasses using batch strategy
+      #
+      # @param result [Object] Result object to populate
+      # @return [void]
+      def resolve_batch(result)
+        raise NotImplementedError, "Subclass must implement resolve_batch for :batch strategy"
+      end
+
+      # Resolve a boundary/section (for :boundary strategy)
+      # Override this method in subclasses using boundary strategy
+      #
+      # Boundaries represent sections of content where template and destination
+      # differ. This strategy is useful for ASTs where content is processed
+      # in ranges/sections rather than individual nodes or all at once.
+      #
+      # @param boundary [Object] Boundary object with template_range and dest_range
+      # @param result [Object] Result object to populate
+      # @return [void]
+      def resolve_boundary(boundary, result)
+        raise NotImplementedError, "Subclass must implement resolve_boundary for :boundary strategy"
+      end
+
+      # Build a signature map from nodes
+      # Useful for batch resolution strategy
+      #
+      # @param nodes [Array] Nodes to map
+      # @param analysis [Object] Analysis for signature generation
+      # @return [Hash] Map of signature => [{node:, index:}, ...]
+      def build_signature_map(nodes, analysis)
+        map = {}
+        nodes.each_with_index do |node, idx|
+          sig = analysis.generate_signature(node)
+          next unless sig
+
+          map[sig] ||= []
+          map[sig] << {node: node, index: idx}
+        end
+        map
+      end
+
+      # Build a signature map from node_info hashes
+      # Useful for boundary resolution strategy where nodes are wrapped in info hashes
+      #
+      # @param node_infos [Array<Hash>] Node info hashes with :signature and :index keys
+      # @return [Hash] Map of signature => [node_info, ...]
+      def build_signature_map_from_infos(node_infos)
+        map = Hash.new { |h, k| h[k] = [] }
+        node_infos.each do |node_info|
+          sig = node_info[:signature]
+          map[sig] << node_info if sig
+        end
+        map
+      end
+
+      # Check if two line ranges overlap
+      #
+      # @param range1 [Range] First range
+      # @param range2 [Range] Second range
+      # @return [Boolean] True if ranges overlap
+      def ranges_overlap?(range1, range2)
+        range1.begin <= range2.end && range2.begin <= range1.end
+      end
+
+      # Create a resolution hash for frozen block
+      #
+      # @param source [Symbol] :template or :destination
+      # @param template_node [Object] Template node
+      # @param dest_node [Object] Destination node
+      # @param reason [String, nil] Freeze reason
+      # @return [Hash] Resolution hash
+      def frozen_resolution(source:, template_node:, dest_node:, reason: nil)
+        {
+          source: source,
+          decision: DECISION_FROZEN,
+          template_node: template_node,
+          dest_node: dest_node,
+          reason: reason,
+        }
+      end
+
+      # Create a resolution hash for identical content
+      #
+      # @param template_node [Object] Template node
+      # @param dest_node [Object] Destination node
+      # @return [Hash] Resolution hash
+      def identical_resolution(template_node:, dest_node:)
+        {
+          source: :destination,
+          decision: DECISION_IDENTICAL,
+          template_node: template_node,
+          dest_node: dest_node,
+        }
+      end
+
+      # Create a resolution hash based on preference.
+      # Supports per-node-type preferences when a Hash is configured.
+      #
+      # When per-type preferences are configured, checks template_node for
+      # merge_type (from NodeTyping wrapping). If template_node has no merge_type,
+      # falls back to dest_node's merge_type, then to the default preference.
+      #
+      # @param template_node [Object] Template node (may be a Wrapper)
+      # @param dest_node [Object] Destination node (may be a Wrapper)
+      # @return [Hash] Resolution hash
+      def preference_resolution(template_node:, dest_node:)
+        # Get the appropriate preference for this node pair
+        # Template node's merge_type takes precedence, then dest_node's
+        node_preference = if NodeTyping.typed_node?(template_node)
+          preference_for_node(template_node)
+        elsif NodeTyping.typed_node?(dest_node)
+          preference_for_node(dest_node)
+        else
+          default_preference
+        end
+
+        if node_preference == :template
+          {
+            source: :template,
+            decision: DECISION_TEMPLATE,
+            template_node: template_node,
+            dest_node: dest_node,
+          }
+        else
+          {
+            source: :destination,
+            decision: DECISION_DESTINATION,
+            template_node: template_node,
+            dest_node: dest_node,
+          }
+        end
+      end
+
+      private
+
+      # Validate the preference parameter.
+      #
+      # @param preference [Symbol, Hash] The preference to validate
+      # @raise [ArgumentError] If preference is invalid
+      def validate_preference!(preference)
+        if preference.is_a?(Hash)
+          validate_hash_preference!(preference)
+        elsif !%i[destination template].include?(preference)
+          raise ArgumentError, "Invalid preference: #{preference}. Must be :destination, :template, or a Hash"
+        end
+      end
+
+      # Validate a Hash preference configuration.
+      #
+      # @param preference [Hash] The preference hash to validate
+      # @raise [ArgumentError] If any key or value is invalid
+      def validate_hash_preference!(preference)
+        preference.each do |key, value|
+          unless key.is_a?(Symbol)
+            raise ArgumentError,
+              "preference Hash keys must be Symbols, got #{key.class} for #{key.inspect}"
+          end
+
+          unless %i[destination template].include?(value)
+            raise ArgumentError,
+              "preference Hash values must be :destination or :template, " \
+                "got #{value.inspect} for key #{key.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/debug_logger.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base debug logging utility for AST merge libraries.
+    # Provides conditional debug output based on environment configuration.
+    #
+    # This module is designed to be extended by file-type-specific merge libraries
+    # (e.g., Prism::Merge, Psych::Merge) which configure their own environment
+    # variable and log prefix.
+    #
+    # == Minimal Integration
+    #
+    # Simply extend this module and configure your environment variable and log prefix:
+    #
+    # @example Creating a custom debug logger (minimal integration)
+    #   module MyMerge
+    #     module DebugLogger
+    #       extend Ast::Merge::DebugLogger
+    #
+    #       self.env_var_name = "MY_MERGE_DEBUG"
+    #       self.log_prefix = "[MyMerge]"
+    #     end
+    #   end
+    #
+    # == Overriding Methods
+    #
+    # When you +extend+ a module, its instance methods become singleton methods on
+    # your module. To override inherited behavior, you must define *singleton methods*
+    # (+def self.method_name+), not instance methods (+def method_name+).
+    #
+    # @example Overriding a method (correct - singleton method)
+    #   module MyMerge
+    #     module DebugLogger
+    #       extend Ast::Merge::DebugLogger
+    #
+    #       self.env_var_name = "MY_MERGE_DEBUG"
+    #       self.log_prefix = "[MyMerge]"
+    #
+    #       # Override extract_node_info for custom node types
+    #       def self.extract_node_info(node)
+    #         case node
+    #         when MyMerge::CustomNode
+    #           {type: "CustomNode", lines: "#{node.start_line}..#{node.end_line}"}
+    #         else
+    #           # Delegate to base implementation
+    #           Ast::Merge::DebugLogger.extract_node_info(node)
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @example Enable debug logging
+    #   ENV['AST_MERGE_DEBUG'] = '1'
+    #   Ast::Merge::DebugLogger.debug("Processing node", {type: "mapping", line: 5})
+    #
+    # == Testing with Shared Examples
+    #
+    # Use the provided shared examples to validate your integration:
+    #
+    #   require "ast/merge/rspec/shared_examples"
+    #
+    #   RSpec.describe MyMerge::DebugLogger do
+    #     it_behaves_like "Ast::Merge::DebugLogger" do
+    #       let(:described_logger) { MyMerge::DebugLogger }
+    #       let(:env_var_name) { "MY_MERGE_DEBUG" }
+    #       let(:log_prefix) { "[MyMerge]" }
+    #     end
+    #   end
+    #
+    # @note Shared examples require +silent_stream+ and +rspec-stubbed_env+ gems.
+    module DebugLogger
+      # Benchmark is optional - gracefully degrade if not available
+      BENCHMARK_AVAILABLE = begin
+        require "benchmark"
+        true
+      rescue LoadError
+        # :nocov:
+        # Platform-specific: benchmark is part of Ruby stdlib, LoadError only on unusual Ruby builds
+        false
+        # :nocov:
+      end
+
+      class << self
+        # @return [String] Environment variable name to check for debug mode
+        attr_accessor :env_var_name
+
+        # @return [String] Prefix for log messages
+        attr_accessor :log_prefix
+
+        # Hook called when a module extends Ast::Merge::DebugLogger.
+        # Sets up attr_accessor for env_var_name and log_prefix on the extending module,
+        # and copies the BENCHMARK_AVAILABLE constant.
+        #
+        # @param base [Module] The module that is extending this module
+        def extended(base)
+          # Create a module with the accessors and prepend it to the singleton class.
+          # This avoids "method redefined" warnings when extending multiple times.
+          accessors_module = Module.new do
+            attr_accessor :env_var_name
+            attr_accessor :log_prefix
+          end
+          base.singleton_class.prepend(accessors_module)
+
+          # Set default values (inherit from Ast::Merge::DebugLogger)
+          base.env_var_name = env_var_name
+          base.log_prefix = log_prefix
+
+          # Copy the BENCHMARK_AVAILABLE constant
+          base.const_set(:BENCHMARK_AVAILABLE, BENCHMARK_AVAILABLE) unless base.const_defined?(:BENCHMARK_AVAILABLE)
+        end
+      end
+
+      # Default configuration
+      self.env_var_name = "AST_MERGE_DEBUG"
+      self.log_prefix = "[Ast::Merge]"
+
+      # Check if debug mode is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        val = ENV[env_var_name]
+        %w[1 true].include?(val)
+      end
+
+      # Get the environment variable name.
+      # When called as a module method (via extend self), returns own config.
+      # When called as instance method, checks class first, then falls back to base.
+      #
+      # @return [String]
+      def env_var_name
+        if is_a?(Module) && singleton_class.method_defined?(:env_var_name)
+          # Called as module method on a module that extended us
+          (self.class.superclass == Module) ? @env_var_name : self.class.env_var_name
+        elsif self.class.respond_to?(:env_var_name)
+          self.class.env_var_name
+        else
+          Ast::Merge::DebugLogger.env_var_name
+        end
+      end
+
+      # Get the log prefix.
+      # When called as a module method (via extend self), returns own config.
+      # When called as instance method, checks class first, then falls back to base.
+      #
+      # @return [String]
+      def log_prefix
+        if is_a?(Module) && singleton_class.method_defined?(:log_prefix)
+          # Called as module method on a module that extended us
+          (self.class.superclass == Module) ? @log_prefix : self.class.log_prefix
+        elsif self.class.respond_to?(:log_prefix)
+          self.class.log_prefix
+        else
+          Ast::Merge::DebugLogger.log_prefix
+        end
+      end
+
+      # Log a debug message with optional context
+      #
+      # @param message [String] The debug message
+      # @param context [Hash] Optional context to include
+      def debug(message, context = {})
+        return unless enabled?
+
+        output = "#{log_prefix} #{message}"
+        output += " #{context.inspect}" unless context.empty?
+        warn(output)
+      end
+
+      # Log an info message (always shown when debug is enabled)
+      #
+      # @param message [String] The info message
+      def info(message)
+        return unless enabled?
+
+        warn("#{log_prefix} INFO] #{message}")
+      end
+
+      # Log a warning message (always shown)
+      #
+      # @param message [String] The warning message
+      def warning(message)
+        warn("#{log_prefix} WARNING] #{message}")
+      end
+
+      # Time a block and log the duration
+      #
+      # @param operation [String] Name of the operation
+      # @yield The block to time
+      # @return [Object] The result of the block
+      def time(operation)
+        return yield unless enabled?
+
+        unless BENCHMARK_AVAILABLE
+          warning("Benchmark gem not available - timing disabled for: #{operation}")
+          return yield
+        end
+
+        debug("Starting: #{operation}")
+        result = nil
+        timing = Benchmark.measure { result = yield }
+        debug("Completed: #{operation}", {
+          real_ms: (timing.real * 1000).round(2),
+          user_ms: (timing.utime * 1000).round(2),
+          system_ms: (timing.stime * 1000).round(2),
+        })
+        result
+      end
+
+      # Log node information - override in submodules for file-type-specific logging
+      #
+      # @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 = extract_node_info(node)
+        debug(label, info)
+      end
+
+      # Extract information from a node for logging.
+      # Override in submodules for file-type-specific node types.
+      #
+      # @param node [Object] Node to extract info from
+      # @return [Hash] Node information
+      def extract_node_info(node)
+        type_name = safe_type_name(node)
+        lines = extract_lines(node)
+
+        info = {type: type_name}
+        info[:lines] = lines if lines
+        info
+      end
+
+      # Safely extract the type name from a node
+      #
+      # @param node [Object] Node to get type from
+      # @return [String] Type name
+      def safe_type_name(node)
+        klass = node.class
+        if klass.respond_to?(:name) && klass.name
+          klass.name.split("::").last
+        else
+          klass.to_s
+        end
+      rescue StandardError
+        node.class.to_s
+      end
+
+      # Extract line information from a node if available
+      #
+      # @param node [Object] Node to extract lines from
+      # @return [String, nil] Line range string or nil
+      def extract_lines(node)
+        if node.respond_to?(:location)
+          loc = node.location
+          if loc.respond_to?(:start_line) && loc.respond_to?(:end_line)
+            "#{loc.start_line}..#{loc.end_line}"
+          elsif loc.respond_to?(:start_line)
+            loc.start_line.to_s
+          end
+        elsif node.respond_to?(:start_line) && node.respond_to?(:end_line)
+          "#{node.start_line}..#{node.end_line}"
+        end
+      end
+
+      # Make all methods available as both instance and module methods
+      extend self
+    end
+  end
+end