ast-merge 3.1.0 → 4.0.0

data/exe/ast-merge-recipe

@@ -185,6 +185,10 @@ class AstMergeRecipeCLI
         @options[:verbose] = true
       end
 
+      opts.on("--show-problems", "Show document problems found during merge") do
+        @options[:show_problems] = true
+      end
+
       opts.on(
         "-p",
         "--parser=PARSER",
@@ -318,6 +322,22 @@ class AstMergeRecipeCLI
       puts Colors.dim("      Stats: #{result.stats.inspect}")
     end
 
+    # Show problems if --show-problems or --verbose
+    if (@options[:show_problems] || @options[:verbose]) && result.problems&.any?
+      puts Colors.yellow("      Problems:")
+      result.problems.each do |problem|
+        severity_color = case problem[:severity]
+        when :error then :red
+        when :warning then :yellow
+        else :dim
+        end
+        msg = "        [#{problem[:severity]}] #{problem[:category]}"
+        details = problem.reject { |k, _| [:category, :severity].include?(k) }
+        msg += ": #{details.inspect}" unless details.empty?
+        puts Colors.send(severity_color, msg)
+      end
+    end
+
     if result.error && @options[:verbose]
       puts Colors.red("      #{result.error.class}: #{result.error.message}")
       puts Colors.dim("      #{result.error.backtrace&.first(3)&.join("\n      ")}")

data/lib/ast/merge/conflict_resolver_base.rb

@@ -118,6 +118,15 @@ module Ast
       # @return [Boolean] Whether to add template-only nodes (batch strategy)
       attr_reader :add_template_only_nodes
 
+      # @return [Boolean] Whether to remove destination nodes not in template (batch strategy)
+      attr_reader :remove_template_missing_nodes
+
+      # @return [Boolean, Integer] Whether to merge nested structures recursively
+      #   - true: unlimited depth (default)
+      #   - false: disabled
+      #   - Integer > 0: max depth
+      attr_reader :recursive
+
       # @return [Object, nil] Match refiner for fuzzy matching
       attr_reader :match_refiner
 
@@ -132,20 +141,29 @@ module Ast
       # @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)
+      # @param remove_template_missing_nodes [Boolean] Whether to remove destination nodes not in template
+      # @param recursive [Boolean, Integer] Whether to merge nested structures recursively
+      #   - true: unlimited depth (default)
+      #   - false: disabled
+      #   - Integer > 0: max depth
+      #   - 0: invalid, raises ArgumentError
       # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching
       # @param options [Hash] Additional options for forward compatibility
-      def initialize(strategy:, preference:, template_analysis:, dest_analysis:, add_template_only_nodes: false, match_refiner: nil, **options)
+      def initialize(strategy:, preference:, template_analysis:, dest_analysis:, add_template_only_nodes: false, remove_template_missing_nodes: false, recursive: true, match_refiner: nil, **options)
         unless %i[node batch boundary].include?(strategy)
           raise ArgumentError, "Invalid strategy: #{strategy}. Must be :node, :batch, or :boundary"
         end
 
         validate_preference!(preference)
+        validate_recursive!(recursive)
 
         @strategy = strategy
         @preference = preference
         @template_analysis = template_analysis
         @dest_analysis = dest_analysis
         @add_template_only_nodes = add_template_only_nodes
+        @remove_template_missing_nodes = remove_template_missing_nodes
+        @recursive = recursive
         @match_refiner = match_refiner
         # **options captured for forward compatibility - subclasses may use additional options
       end
@@ -401,6 +419,34 @@ module Ast
           end
         end
       end
+
+      # Validate the recursive parameter.
+      #
+      # @param recursive [Boolean, Integer] The recursive value to validate
+      # @raise [ArgumentError] If recursive is invalid
+      def validate_recursive!(recursive)
+        return if recursive == true || recursive == false
+        return if recursive.is_a?(Integer) && recursive > 0
+
+        if recursive == 0
+          raise ArgumentError, "recursive: 0 is invalid, use false to disable recursive merging"
+        end
+
+        raise ArgumentError,
+          "Invalid recursive: #{recursive.inspect}. Must be true, false, or a positive Integer"
+      end
+
+      # Check if recursive merging should be applied at a given depth.
+      #
+      # @param current_depth [Integer] Current recursion depth (0 = root level)
+      # @return [Boolean] Whether to continue recursive merging
+      def should_recurse?(current_depth)
+        return false if @recursive == false
+        return true if @recursive == true
+
+        # @recursive is a positive Integer representing max depth
+        current_depth < @recursive
+      end
     end
   end
 end

data/lib/ast/merge/diff_mapper_base.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for mapping unified git diffs to AST node paths.
+    #
+    # DiffMapperBase provides a format-agnostic foundation for parsing unified
+    # git diffs and mapping changed lines to AST node paths. Subclasses implement
+    # format-specific logic to determine which AST nodes are affected by each change.
+    #
+    # @example Basic usage with a subclass
+    #   class Psych::Merge::DiffMapper < Ast::Merge::DiffMapperBase
+    #     def map_hunk_to_paths(hunk, original_analysis)
+    #       # YAML-specific implementation
+    #     end
+    #   end
+    #
+    #   mapper = Psych::Merge::DiffMapper.new
+    #   mappings = mapper.map(diff_text, original_content)
+    #
+    # @abstract Subclass and implement {#map_hunk_to_paths}
+    class DiffMapperBase
+      # Represents a single hunk from a unified diff
+      DiffHunk = Struct.new(
+        :old_start,    # Starting line in original file (1-based)
+        :old_count,    # Number of lines in original
+        :new_start,    # Starting line in new file (1-based)
+        :new_count,    # Number of lines in new file
+        :lines,        # Array of DiffLine objects
+        :header,       # The @@ header line
+        keyword_init: true,
+      )
+
+      # Represents a single line in a diff hunk
+      DiffLine = Struct.new(
+        :type,         # :context, :addition, :removal
+        :content,      # Line content (without +/- prefix)
+        :old_line_num, # Line number in original file (nil for additions)
+        :new_line_num, # Line number in new file (nil for removals)
+        keyword_init: true,
+      )
+
+      # Represents a mapping from diff changes to AST paths
+      DiffMapping = Struct.new(
+        :path,         # Array of keys/indices representing AST path (e.g., ["AllCops", "Exclude"])
+        :operation,    # :add, :remove, or :modify
+        :lines,        # Array of DiffLine objects for this path
+        :hunk,         # The source DiffHunk
+        keyword_init: true,
+      )
+
+      # Result of parsing a diff file
+      DiffParseResult = Struct.new(
+        :old_file,     # Original file path from --- line
+        :new_file,     # New file path from +++ line
+        :hunks,        # Array of DiffHunk objects
+        keyword_init: true,
+      )
+
+      # Parse a unified diff and map changes to AST paths.
+      #
+      # @param diff_text [String] The unified diff content
+      # @param original_content [String] The original file content (for AST path mapping)
+      # @return [Array<DiffMapping>] Mappings from changes to AST paths
+      def map(diff_text, original_content)
+        parse_result = parse_diff(diff_text)
+        return [] if parse_result.hunks.empty?
+
+        original_analysis = create_analysis(original_content)
+
+        parse_result.hunks.flat_map do |hunk|
+          map_hunk_to_paths(hunk, original_analysis)
+        end
+      end
+
+      # Parse a unified diff into structured hunks.
+      #
+      # @param diff_text [String] The unified diff content
+      # @return [DiffParseResult] Parsed diff with file paths and hunks
+      def parse_diff(diff_text)
+        lines = diff_text.lines.map(&:chomp)
+
+        old_file = nil
+        new_file = nil
+        hunks = []
+        current_hunk = nil
+        old_line_num = nil
+        new_line_num = nil
+
+        lines.each do |line|
+          case line
+          when /^---\s+(.+)$/
+            # Original file path
+            old_file = extract_file_path($1)
+          when /^\+\+\+\s+(.+)$/
+            # New file path
+            new_file = extract_file_path($1)
+          when /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/
+            # Hunk header
+            # Finalize previous hunk
+            hunks << current_hunk if current_hunk
+
+            old_start = $1.to_i
+            old_count = ($2 || "1").to_i
+            new_start = $3.to_i
+            new_count = ($4 || "1").to_i
+
+            current_hunk = DiffHunk.new(
+              old_start: old_start,
+              old_count: old_count,
+              new_start: new_start,
+              new_count: new_count,
+              lines: [],
+              header: line,
+            )
+            old_line_num = old_start
+            new_line_num = new_start
+          when /^\+(.*)$/
+            # Addition (not +++ header line, already handled)
+            next unless current_hunk
+
+            current_hunk.lines << DiffLine.new(
+              type: :addition,
+              content: $1,
+              old_line_num: nil,
+              new_line_num: new_line_num,
+            )
+            new_line_num += 1
+          when /^-(.*)$/
+            # Removal (not --- header line, already handled)
+            next unless current_hunk
+
+            current_hunk.lines << DiffLine.new(
+              type: :removal,
+              content: $1,
+              old_line_num: old_line_num,
+              new_line_num: nil,
+            )
+            old_line_num += 1
+          when /^ (.*)$/
+            # Context line
+            next unless current_hunk
+
+            current_hunk.lines << DiffLine.new(
+              type: :context,
+              content: $1,
+              old_line_num: old_line_num,
+              new_line_num: new_line_num,
+            )
+            old_line_num += 1
+            new_line_num += 1
+          end
+        end
+
+        # Finalize last hunk
+        hunks << current_hunk if current_hunk
+
+        DiffParseResult.new(
+          old_file: old_file,
+          new_file: new_file,
+          hunks: hunks,
+        )
+      end
+
+      # Determine the operation type for a hunk.
+      #
+      # @param hunk [DiffHunk] The hunk to analyze
+      # @return [Symbol] :add, :remove, or :modify
+      def determine_operation(hunk)
+        has_additions = hunk.lines.any? { |l| l.type == :addition }
+        has_removals = hunk.lines.any? { |l| l.type == :removal }
+
+        if has_additions && has_removals
+          :modify
+        elsif has_additions
+          :add
+        elsif has_removals
+          :remove
+        else
+          :modify # Context-only hunk (unusual)
+        end
+      end
+
+      # Create a file analysis for the original content.
+      # Subclasses must implement this to return their format-specific analysis.
+      #
+      # @param content [String] The original file content
+      # @return [Object] A FileAnalysis object for the format
+      # @abstract
+      def create_analysis(content)
+        raise NotImplementedError, "Subclasses must implement #create_analysis"
+      end
+
+      # Map a single hunk to AST paths.
+      # Subclasses must implement this with format-specific logic.
+      #
+      # @param hunk [DiffHunk] The hunk to map
+      # @param original_analysis [Object] FileAnalysis of the original content
+      # @return [Array<DiffMapping>] Mappings for this hunk
+      # @abstract
+      def map_hunk_to_paths(hunk, original_analysis)
+        raise NotImplementedError, "Subclasses must implement #map_hunk_to_paths"
+      end
+
+      protected
+
+      # Extract file path from diff header, handling common prefixes.
+      #
+      # @param path_string [String] Path from --- or +++ line
+      # @return [String] Cleaned file path
+      def extract_file_path(path_string)
+        # Remove common prefixes: a/, b/, or timestamp suffixes
+        path_string
+          .sub(%r{^[ab]/}, "")
+          .sub(/\t.*$/, "") # Remove timestamp suffix
+          .strip
+      end
+
+      # Find the AST node that contains a given line number.
+      # Helper method for subclasses.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @param statements [Array] Array of statement nodes
+      # @return [Object, nil] The containing node or nil
+      def find_node_at_line(line_num, statements)
+        statements.find do |node|
+          next unless node.respond_to?(:start_line) && node.respond_to?(:end_line)
+          next unless node.start_line && node.end_line
+
+          line_num >= node.start_line && line_num <= node.end_line
+        end
+      end
+
+      # Build a path array from a node's ancestry.
+      # Helper method for subclasses to override with format-specific logic.
+      #
+      # @param node [Object] The AST node
+      # @param analysis [Object] The file analysis
+      # @return [Array<String, Integer>] Path components
+      def build_path_for_node(node, analysis)
+        raise NotImplementedError, "Subclasses must implement #build_path_for_node"
+      end
+    end
+  end
+end

data/lib/ast/merge/navigable/injection_point.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Navigable
+      # Represents a location in a document where content can be injected.
+      #
+      # InjectionPoint is language-agnostic - it works with any AST structure.
+      # It defines WHERE to inject content and HOW (as child, sibling, or replacement).
+      #
+      # @example Inject as first child of a class
+      #   point = InjectionPoint.new(
+      #     anchor: class_node,
+      #     position: :first_child
+      #   )
+      #
+      # @example Inject after a specific method
+      #   point = InjectionPoint.new(
+      #     anchor: method_node,
+      #     position: :after
+      #   )
+      #
+      # @example Replace a range of nodes
+      #   point = InjectionPoint.new(
+      #     anchor: start_node,
+      #     position: :replace,
+      #     boundary: end_node
+      #   )
+      #
+      class InjectionPoint
+        # Valid positions for injection
+        POSITIONS = %i[
+          before
+          after
+          first_child
+          last_child
+          replace
+        ].freeze
+
+        # @return [Statement] The anchor node for injection
+        attr_reader :anchor
+
+        # @return [Symbol] Position relative to anchor (:before, :after, :first_child, :last_child, :replace)
+        attr_reader :position
+
+        # @return [Statement, nil] End boundary for :replace position
+        attr_reader :boundary
+
+        # @return [Hash] Additional metadata about this injection point
+        attr_reader :metadata
+
+        # Initialize an InjectionPoint.
+        #
+        # @param anchor [Statement] The reference node
+        # @param position [Symbol] Where to inject relative to anchor
+        # @param boundary [Statement, nil] End boundary for replacements
+        # @param metadata [Hash] Additional info (e.g., match details)
+        def initialize(anchor:, position:, boundary: nil, **metadata)
+          validate_position!(position)
+          validate_boundary!(position, boundary)
+
+          @anchor = anchor
+          @position = position
+          @boundary = boundary
+          @metadata = metadata
+        end
+
+        # @return [Boolean] true if this is a replacement (not insertion)
+        def replacement?
+          position == :replace
+        end
+
+        # @return [Boolean] true if this injects as a child
+        def child_injection?
+          %i[first_child last_child].include?(position)
+        end
+
+        # @return [Boolean] true if this injects as a sibling
+        def sibling_injection?
+          %i[before after].include?(position)
+        end
+
+        # Get all statements that would be replaced.
+        #
+        # @return [Array<Statement>] Statements to replace (empty if not replacement)
+        def replaced_statements
+          return [] unless replacement?
+          return [anchor] unless boundary
+
+          result = [anchor]
+          current = anchor.next
+          while current && current != boundary
+            result << current
+            current = current.next
+          end
+          result << boundary if boundary
+          result
+        end
+
+        # @return [Integer, nil] Start line of injection point
+        def start_line
+          anchor.start_line
+        end
+
+        # @return [Integer, nil] End line of injection point
+        def end_line
+          (boundary || anchor).end_line
+        end
+
+        # @return [String] Human-readable representation
+        def inspect
+          boundary_info = boundary ? " to #{boundary.index}" : ""
+          "#<Navigable::InjectionPoint position=#{position} anchor=#{anchor.index}#{boundary_info}>"
+        end
+
+        private
+
+        def validate_position!(position)
+          return if POSITIONS.include?(position)
+
+          raise ArgumentError, "Invalid position: #{position}. Must be one of: #{POSITIONS.join(", ")}"
+        end
+
+        def validate_boundary!(position, boundary)
+          return unless boundary && position != :replace
+
+          raise ArgumentError, "boundary is only valid with position: :replace"
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/navigable/injection_point_finder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Navigable
+      # Finds injection points in a document based on matching rules.
+      #
+      # This is language-agnostic - the matching rules work on the unified
+      # Statement interface regardless of the underlying parser.
+      #
+      # @example Find where to inject constants in a Ruby class
+      #   finder = InjectionPointFinder.new(statements)
+      #   point = finder.find(
+      #     type: :class,
+      #     text: /class Choo/,
+      #     position: :first_child
+      #   )
+      #
+      # @example Find and replace a constant definition
+      #   point = finder.find(
+      #     type: :constant_assignment,
+      #     text: /DAR\s*=/,
+      #     position: :replace
+      #   )
+      #
+      class InjectionPointFinder
+        # @return [Array<Statement>] The statement list to search
+        attr_reader :statements
+
+        def initialize(statements)
+          @statements = statements
+        end
+
+        # Find an injection point based on matching criteria.
+        #
+        # @param type [Symbol, String, nil] Node type to match
+        # @param text [String, Regexp, nil] Text pattern to match
+        # @param position [Symbol] Where to inject (:before, :after, :first_child, :last_child, :replace)
+        # @param boundary_type [Symbol, String, nil] Node type for replacement boundary
+        # @param boundary_text [String, Regexp, nil] Text pattern for replacement boundary
+        # @param boundary_matcher [Proc, nil] Custom matcher for boundary (receives Statement, returns boolean)
+        # @param boundary_same_or_shallower [Boolean] If true, boundary is next node at same or shallower tree depth
+        # @yield [Statement] Optional custom matcher
+        # @return [InjectionPoint, nil] Injection point if anchor found
+        def find(type: nil, text: nil, position:, boundary_type: nil, boundary_text: nil, boundary_matcher: nil, boundary_same_or_shallower: false, &block)
+          anchor = Statement.find_first(statements, type: type, text: text, &block)
+          return unless anchor
+
+          boundary = nil
+          if position == :replace && (boundary_type || boundary_text || boundary_matcher || boundary_same_or_shallower)
+            # Find boundary starting after anchor
+            remaining = statements[(anchor.index + 1)..]
+
+            if boundary_same_or_shallower
+              # Find next node at same or shallower tree depth
+              # This is language-agnostic: ends section at next sibling or ancestor's sibling
+              anchor_depth = anchor.tree_depth
+              boundary = remaining.find do |stmt|
+                # Must match type if specified
+                next false if boundary_type && stmt.type.to_s != boundary_type.to_s
+                next false if boundary_text && !stmt.text_matches?(boundary_text)
+                # Check tree depth
+                stmt.same_or_shallower_than?(anchor_depth)
+              end
+            elsif boundary_matcher
+              # Use custom matcher
+              boundary = remaining.find { |stmt| boundary_matcher.call(stmt) }
+            else
+              boundary = Statement.find_first(
+                remaining,
+                type: boundary_type,
+                text: boundary_text,
+              )
+            end
+          end
+
+          InjectionPoint.new(
+            anchor: anchor,
+            position: position,
+            boundary: boundary,
+            match: {type: type, text: text},
+          )
+        end
+
+        # Find all injection points matching criteria.
+        #
+        # @param (see #find)
+        # @return [Array<InjectionPoint>] All matching injection points
+        def find_all(type: nil, text: nil, position:, &block)
+          anchors = Statement.find_matching(statements, type: type, text: text, &block)
+          anchors.map do |anchor|
+            InjectionPoint.new(anchor: anchor, position: position)
+          end
+        end
+      end
+    end
+  end
+end