ast-merge 3.0.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/emitter_base.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for emitters that convert AST structures back to text.
+    # Provides common functionality for tracking indentation, managing output lines,
+    # and handling comments.
+    #
+    # Subclasses implement format-specific emission methods (e.g., emit_pair for JSON,
+    # emit_variable_assignment for Bash, etc.)
+    #
+    # @example Implementing a custom emitter
+    #   class MyEmitter < Ast::Merge::EmitterBase
+    #     def emit_my_construct(data)
+    #       add_comma_if_needed if @needs_separator
+    #       @lines << "#{current_indent}my_syntax: #{data}"
+    #       @needs_separator = true
+    #     end
+    #   end
+    class EmitterBase
+      # @return [Array<String>] Output lines
+      attr_reader :lines
+
+      # @return [Integer] Current indentation level
+      attr_reader :indent_level
+
+      # @return [Integer] Spaces per indent level
+      attr_reader :indent_size
+
+      # Initialize a new emitter
+      #
+      # @param indent_size [Integer] Number of spaces per indent level
+      # @param options [Hash] Additional options for subclasses
+      def initialize(indent_size: 2, **options)
+        @lines = []
+        @indent_level = 0
+        @indent_size = indent_size
+        initialize_subclass_state(**options)
+      end
+
+      # Hook for subclasses to initialize their own state
+      # @param options [Hash] Additional options
+      def initialize_subclass_state(**options)
+        # Override in subclasses if needed
+      end
+
+      # Emit a blank line
+      def emit_blank_line
+        @lines << ""
+      end
+
+      # Emit leading comments from CommentTracker
+      #
+      # @param comments [Array<Hash>] Comment hashes with :text, :indent, etc.
+      def emit_leading_comments(comments)
+        comments.each do |comment|
+          emit_tracked_comment(comment)
+        end
+      end
+
+      # Emit a comment from CommentTracker hash
+      # Subclasses should override this to handle format-specific comment syntax
+      #
+      # @param comment [Hash] Comment hash with :text, :indent, :block, etc.
+      def emit_tracked_comment(comment)
+        raise NotImplementedError, "Subclasses must implement emit_tracked_comment"
+      end
+
+      # Emit raw lines as-is (for preserving exact formatting)
+      #
+      # @param raw_lines [Array<String>] Lines to emit without modification
+      def emit_raw_lines(raw_lines)
+        raw_lines.each { |line| @lines << line.chomp }
+      end
+
+      # Get the output as a single string
+      # Subclasses may override to customize output format (e.g., to_json, to_yaml)
+      #
+      # @return [String]
+      def to_s
+        content = @lines.join("\n")
+        content += "\n" unless content.empty? || content.end_with?("\n")
+        content
+      end
+
+      # Clear the emitter state
+      def clear
+        @lines = []
+        @indent_level = 0
+        clear_subclass_state
+      end
+
+      # Hook for subclasses to clear their own state
+      def clear_subclass_state
+        # Override in subclasses if needed
+      end
+
+      # Increase indentation level
+      def indent
+        @indent_level += 1
+      end
+
+      # Decrease indentation level
+      def dedent
+        @indent_level -= 1 if @indent_level > 0
+      end
+
+      protected
+
+      # Get the current indentation string
+      # @return [String]
+      def current_indent
+        " " * (@indent_level * @indent_size)
+      end
+
+      # Add a line with current indentation
+      # @param content [String] Line content
+      def add_indented_line(content)
+        @lines << "#{current_indent}#{content}"
+      end
+    end
+  end
+end

data/lib/ast/merge/freeze_node_base.rb

@@ -354,6 +354,15 @@ module Ast
         true
       end
 
+      # Node type for merge classification
+      # @return [Symbol] :freeze_block
+      def merge_type
+        :freeze_block
+      end
+
+      # Alias for compatibility
+      alias_method :type, :merge_type
+
       # Returns a stable signature for this freeze block.
       # Override in subclasses for file-type-specific normalization.
       # @return [Array] Signature array

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