prism-merge 1.0.0

data/lib/prism/merge/merge_result.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Prism
+  module Merge
+    # Represents the merged output with bidirectional links to source lines.
+    # Tracks merge decisions and provenance for validation and debugging.
+    class MergeResult
+      # Line was kept from template (no conflict or template preferred).
+      # Used when template content is included without modification.
+      DECISION_KEPT_TEMPLATE = :kept_template
+
+      # Line was kept from destination (no conflict or destination preferred).
+      # Used when destination content is included without modification.
+      DECISION_KEPT_DEST = :kept_destination
+
+      # Line was appended from destination (destination-only content).
+      # Used for content that exists only in destination and is added to result.
+      # Common for destination-specific customizations like extra methods or constants.
+      DECISION_APPENDED = :appended
+
+      # Line replaced matching content (signature match with preference applied).
+      # Used when template and destination have nodes with same signature but
+      # different content, and one version replaced the other based on preference.
+      DECISION_REPLACED = :replaced
+
+      # Line from destination freeze block (always preserved).
+      # Used for content within kettle-dev:freeze markers that must be kept
+      # from destination regardless of template content.
+      DECISION_FREEZE_BLOCK = :freeze_block
+
+      attr_reader :lines, :line_metadata
+
+      def initialize
+        @lines = []
+        @line_metadata = []
+      end
+
+      # Add a line to the result
+      # @param content [String] Line content (without newline)
+      # @param decision [Symbol] How this line was decided
+      # @param template_line [Integer, nil] 1-based line number from template
+      # @param dest_line [Integer, nil] 1-based line number from destination
+      # @param comment [String, nil] Optional note about this decision
+      def add_line(content, decision:, template_line: nil, dest_line: nil, comment: nil)
+        @lines << content
+        @line_metadata << {
+          decision: decision,
+          template_line: template_line,
+          dest_line: dest_line,
+          comment: comment,
+          result_line: @lines.length,
+        }
+      end
+
+      # Add multiple lines from a source with same decision
+      # @param source_lines [Array<String>] Lines to add
+      # @param decision [Symbol] Merge decision
+      # @param source [Symbol] :template or :destination
+      # @param start_line [Integer] Starting line number in source
+      # @param comment [String, nil] Optional note
+      def add_lines_from(source_lines, decision:, source:, start_line:, comment: nil)
+        source_lines.each_with_index do |line, idx|
+          line_num = start_line + idx
+          if source == :template
+            add_line(line, decision: decision, template_line: line_num, comment: comment)
+          else
+            add_line(line, decision: decision, dest_line: line_num, comment: comment)
+          end
+        end
+      end
+
+      # Add a node's content with its comments
+      # @param node_info [Hash] Node information from FileAnalysis
+      # @param decision [Symbol] Merge decision
+      # @param source [Symbol] :template or :destination
+      # @param source_analysis [FileAnalysis] Source file analysis (unused but kept for compatibility)
+      def add_node(node_info, decision:, source:, source_analysis: nil)
+        node = node_info[:node]
+        start_line = node.location.start_line
+
+        # Add leading comments
+        node_info[:leading_comments].each do |comment|
+          line = comment.slice.rstrip
+          comment_line = comment.location.start_line
+          if source == :template
+            add_line(line, decision: decision, template_line: comment_line)
+          else
+            add_line(line, decision: decision, dest_line: comment_line)
+          end
+        end
+
+        # Add node source
+        node_source = node.slice
+        node_lines = node_source.lines(chomp: true)
+
+        # Handle inline comments
+        inline_comments = node_info[:inline_comments]
+        if inline_comments.any?
+          # Inline comments are on the last line
+          last_idx = node_lines.length - 1
+          if last_idx >= 0
+            inline_text = inline_comments.map { |c| c.slice.strip }.join(" ")
+            node_lines[last_idx] = node_lines[last_idx].rstrip + " " + inline_text
+          end
+        end
+
+        node_lines.each_with_index do |line, idx|
+          line_num = start_line + idx
+          if source == :template
+            add_line(line, decision: decision, template_line: line_num)
+          else
+            add_line(line, decision: decision, dest_line: line_num)
+          end
+        end
+      end
+
+      # Convert to final merged content string
+      # @return [String]
+      def to_s
+        @lines.join("\n") + "\n"
+      end
+
+      # Get statistics about merge decisions
+      # @return [Hash<Symbol, Integer>]
+      def statistics
+        stats = Hash.new(0)
+        @line_metadata.each do |meta|
+          stats[meta[:decision]] += 1
+        end
+        stats
+      end
+
+      # Get lines by decision type
+      # @param decision [Symbol] Decision type to filter by
+      # @return [Array<Hash>] Metadata for matching lines
+      def lines_by_decision(decision)
+        @line_metadata.select { |meta| meta[:decision] == decision }
+      end
+
+      # Debug output showing merge provenance
+      # @return [String]
+      def debug_output
+        output = ["=== Merge Result Debug ==="]
+        output << "Total lines: #{@lines.length}"
+        output << "Statistics: #{statistics.inspect}"
+        output << ""
+        output << "Line-by-line provenance:"
+
+        @lines.each_with_index do |line, idx|
+          meta = @line_metadata[idx]
+          parts = [
+            "#{idx + 1}:".rjust(4),
+            meta[:decision].to_s.ljust(20),
+          ]
+
+          parts << if meta[:template_line]
+            "T:#{meta[:template_line]}".ljust(8)
+          else
+            " " * 8
+          end
+
+          parts << if meta[:dest_line]
+            "D:#{meta[:dest_line]}".ljust(8)
+          else
+            " " * 8
+          end
+
+          parts << "| #{line[0..60]}"
+          output << parts.join(" ")
+        end
+
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/prism/merge/smart_merger.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Prism
+  module Merge
+    # Orchestrates the smart merge process using FileAnalysis, FileAligner,
+    # ConflictResolver, and MergeResult to merge two Ruby files intelligently.
+    #
+    # SmartMerger provides flexible configuration for different merge scenarios:
+    #
+    # @example Basic merge (destination customizations preserved)
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   result = merger.merge
+    #
+    # @example Version file merge (template updates win)
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     signature_match_preference: :template,
+    #     add_template_only_nodes: true
+    #   )
+    #   result = merger.merge
+    #   # Result: VERSION = "2.0.0" (from template), new constants added
+    #
+    # @example Appraisals merge (destination customizations preserved)
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     signature_match_preference: :destination,  # default
+    #     add_template_only_nodes: false             # default
+    #   )
+    #   result = merger.merge
+    #   # Result: Custom gem versions preserved, template-only blocks skipped
+    #
+    # @example Custom signature matching
+    #   sig_gen = ->(node) { [node.class.name, node.name] }
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     signature_generator: sig_gen
+    #   )
+    #
+    # @see FileAnalysis
+    # @see FileAligner
+    # @see ConflictResolver
+    # @see MergeResult
+    class SmartMerger
+      # @return [FileAnalysis] Analysis of the template file
+      attr_reader :template_analysis
+
+      # @return [FileAnalysis] Analysis of the destination file
+      attr_reader :dest_analysis
+
+      # @return [FileAligner] Aligner for finding matches and differences
+      attr_reader :aligner
+
+      # @return [ConflictResolver] Resolver for handling conflicting content
+      attr_reader :resolver
+
+      # @return [MergeResult] Result object tracking merged content
+      attr_reader :result
+
+      # Creates a new SmartMerger for intelligent Ruby file merging.
+      #
+      # @param template_content [String] Template Ruby source code
+      # @param dest_content [String] Destination Ruby source code
+      #
+      # @param signature_generator [Proc, nil] Optional proc to generate custom node signatures.
+      #   The proc receives a Prism node and should return an array representing its signature.
+      #   Nodes with identical signatures are considered matches during merge.
+      #   Default: Uses {FileAnalysis#default_signature} which matches:
+      #   - Conditionals by condition only (not body)
+      #   - Assignments by name only (not value)
+      #   - Method calls by name and args (not block)
+      #
+      # @param signature_match_preference [Symbol] Controls which version to use when nodes
+      #   have matching signatures but different content:
+      #   - `:destination` (default) - Use destination version (preserves customizations).
+      #     Use for Appraisals files, configs with project-specific values.
+      #   - `:template` - Use template version (applies updates).
+      #     Use for version files, canonical configs, conditional implementations.
+      #
+      # @param add_template_only_nodes [Boolean] Controls whether to add nodes that only
+      #   exist in template:
+      #   - `false` (default) - Skip template-only nodes.
+      #     Use for templates with placeholder/example content.
+      #   - `true` - Add template-only nodes to result.
+      #     Use when template has new required constants/methods to add.
+      #
+      # @raise [TemplateParseError] If template has syntax errors
+      # @raise [DestinationParseError] If destination has syntax errors
+      #
+      # @example Basic usage
+      #   merger = SmartMerger.new(template, destination)
+      #   result = merger.merge
+      #
+      # @example Template updates win (version files)
+      #   merger = SmartMerger.new(
+      #     template,
+      #     destination,
+      #     signature_match_preference: :template,
+      #     add_template_only_nodes: true
+      #   )
+      #
+      # @example Destination customizations win (Appraisals)
+      #   merger = SmartMerger.new(
+      #     template,
+      #     destination,
+      #     signature_match_preference: :destination,
+      #     add_template_only_nodes: false
+      #   )
+      #
+      # @example Custom signature matching
+      #   sig_gen = lambda do |node|
+      #     case node
+      #     when Prism::DefNode
+      #       [:method, node.name]
+      #     else
+      #       [node.class.name, node.slice]
+      #     end
+      #   end
+      #
+      #   merger = SmartMerger.new(
+      #     template,
+      #     destination,
+      #     signature_generator: sig_gen
+      #   )
+      def initialize(template_content, dest_content, signature_generator: nil, signature_match_preference: :destination, add_template_only_nodes: false)
+        @template_content = template_content
+        @dest_content = dest_content
+        @signature_match_preference = signature_match_preference
+        @add_template_only_nodes = add_template_only_nodes
+        @template_analysis = FileAnalysis.new(template_content, signature_generator: signature_generator)
+        @dest_analysis = FileAnalysis.new(dest_content, signature_generator: signature_generator)
+        @aligner = FileAligner.new(@template_analysis, @dest_analysis)
+        @resolver = ConflictResolver.new(
+          @template_analysis,
+          @dest_analysis,
+          signature_match_preference: signature_match_preference,
+          add_template_only_nodes: add_template_only_nodes,
+        )
+        @result = MergeResult.new
+      end
+
+      # Performs the intelligent merge of template and destination files.
+      #
+      # The merge process:
+      # 1. Validates both files for syntax errors
+      # 2. Finds anchors (matching sections) and boundaries (differences)
+      # 3. Processes anchors and boundaries in order
+      # 4. Returns merged content as a string
+      #
+      # Merge behavior is controlled by constructor parameters:
+      # - `signature_match_preference`: Which version wins for matching nodes
+      # - `add_template_only_nodes`: Whether to add template-only content
+      #
+      # @return [String] The merged Ruby source code
+      #
+      # @raise [TemplateParseError] If template has syntax errors
+      # @raise [DestinationParseError] If destination has syntax errors
+      #
+      # @example Basic merge
+      #   merger = SmartMerger.new(template, destination)
+      #   result = merger.merge
+      #   File.write("output.rb", result)
+      #
+      # @example With error handling
+      #   begin
+      #     result = merger.merge
+      #   rescue Prism::Merge::TemplateParseError => e
+      #     puts "Template error: #{e.message}"
+      #     puts "Parse errors: #{e.parse_result.errors}"
+      #   end
+      #
+      # @see #merge_with_debug for detailed merge information
+      def merge
+        # Handle invalid files
+        unless @template_analysis.valid?
+          raise Prism::Merge::TemplateParseError.new(
+            "Template file has parsing errors",
+            content: @template_content,
+            parse_result: @template_analysis.parse_result,
+          )
+        end
+
+        unless @dest_analysis.valid?
+          raise Prism::Merge::DestinationParseError.new(
+            "Destination file has parsing errors",
+            content: @dest_content,
+            parse_result: @dest_analysis.parse_result,
+          )
+        end
+
+        # Find anchors and boundaries
+        boundaries = @aligner.align
+
+        # Process the merge by walking through anchors and boundaries in order
+        process_merge(boundaries)
+
+        # Return final content
+        @result.to_s
+      end
+
+      # Performs merge and returns detailed debug information.
+      #
+      # This method provides comprehensive information about merge decisions,
+      # useful for debugging, testing, and understanding merge behavior.
+      #
+      # @return [Hash] Hash containing:
+      #   - `:content` [String] - Final merged content
+      #   - `:debug` [String] - Line-by-line provenance information
+      #   - `:statistics` [Hash] - Counts of merge decisions:
+      #     - `:kept_template` - Lines from template (no conflict)
+      #     - `:kept_destination` - Lines from destination (no conflict)
+      #     - `:replaced` - Template replaced matching destination
+      #     - `:appended` - Destination-only content added
+      #     - `:freeze_block` - Lines from freeze blocks
+      #
+      # @example Get merge statistics
+      #   result = merger.merge_with_debug
+      #   puts "Template lines: #{result[:statistics][:kept_template]}"
+      #   puts "Replaced lines: #{result[:statistics][:replaced]}"
+      #
+      # @example Debug line provenance
+      #   result = merger.merge_with_debug
+      #   puts result[:debug]
+      #   # Output shows source file and decision for each line:
+      #   # Line 1: [KEPT_TEMPLATE] # frozen_string_literal: true
+      #   # Line 2: [KEPT_TEMPLATE]
+      #   # Line 3: [REPLACED] VERSION = "2.0.0"
+      #
+      # @see #merge for basic merge without debug info
+      def merge_with_debug
+        content = merge
+        {
+          content: content,
+          debug: @result.debug_output,
+          statistics: @result.statistics,
+        }
+      end
+
+      private
+
+      def process_merge(boundaries)
+        # Build complete timeline of anchors and boundaries
+        timeline = build_timeline(boundaries)
+
+        timeline.each do |item|
+          if item[:type] == :anchor
+            process_anchor(item[:anchor])
+          else
+            process_boundary(item[:boundary])
+          end
+        end
+      end
+
+      def build_timeline(boundaries)
+        timeline = []
+
+        # Add all anchors and boundaries sorted by position
+        @aligner.anchors.each do |anchor|
+          timeline << {type: :anchor, anchor: anchor, sort_key: [anchor.template_start, 0]}
+        end
+
+        boundaries.each do |boundary|
+          # Sort boundaries by their starting position
+          t_start = boundary.template_range&.begin || 0
+          d_start = boundary.dest_range&.begin || 0
+          sort_key = [t_start, d_start, 1] # 1 ensures boundaries come after anchors at same position
+
+          timeline << {type: :boundary, boundary: boundary, sort_key: sort_key}
+        end
+
+        timeline.sort_by! { |item| item[:sort_key] }
+        timeline
+      end
+
+      def process_anchor(anchor)
+        # Anchors represent identical or equivalent sections - just copy them
+        case anchor.match_type
+        when :freeze_block
+          # Freeze blocks from destination take precedence
+          add_freeze_block_from_dest(anchor)
+        when :signature_match
+          # For signature matches (same structure, different content), prefer destination
+          add_signature_match_from_dest(anchor)
+        when :exact_match
+          # For exact matches, prefer template (it's the source of truth)
+          add_exact_match_from_template(anchor)
+        else
+          # Unknown match type - default to template
+          add_exact_match_from_template(anchor)
+        end
+      end
+
+      def add_freeze_block_from_dest(anchor)
+        anchor.dest_range.each do |line_num|
+          line = @dest_analysis.line_at(line_num)
+          @result.add_line(
+            line.chomp,
+            decision: MergeResult::DECISION_FREEZE_BLOCK,
+            dest_line: line_num,
+          )
+        end
+      end
+
+      def add_signature_match_from_dest(anchor)
+        # For signature matches, use the configured preference
+        if @signature_match_preference == :template
+          # Use template version (for updates/canonical values)
+          anchor.template_range.each do |line_num|
+            line = @template_analysis.line_at(line_num)
+            @result.add_line(
+              line.chomp,
+              decision: MergeResult::DECISION_REPLACED,
+              template_line: line_num,
+            )
+          end
+        else
+          # Use destination version (for customizations)
+          anchor.dest_range.each do |line_num|
+            line = @dest_analysis.line_at(line_num)
+            @result.add_line(
+              line.chomp,
+              decision: MergeResult::DECISION_REPLACED,
+              dest_line: line_num,
+            )
+          end
+        end
+      end
+
+      def add_exact_match_from_template(anchor)
+        anchor.template_range.each do |line_num|
+          line = @template_analysis.line_at(line_num)
+          @result.add_line(
+            line.chomp,
+            decision: MergeResult::DECISION_KEPT_TEMPLATE,
+            template_line: line_num,
+          )
+        end
+      end
+
+      def process_boundary(boundary)
+        @resolver.resolve(boundary, @result)
+      end
+    end
+  end
+end

data/lib/prism/merge/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Prism
+  module Merge
+    # Version information for Prism::Merge
+    module Version
+      # Current version of the prism-merge gem
+      VERSION = "1.0.0"
+    end
+    VERSION = Version::VERSION # traditional location
+  end
+end

data/lib/prism/merge.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# External gems
+require "prism"
+require "version_gem"
+
+# This gem
+require_relative "merge/version"
+
+# Prism::Merge provides a generic Ruby file smart merge system using Prism AST analysis.
+# It intelligently merges template and destination Ruby files by identifying matching
+# sections (anchors) and resolving differences (boundaries) using structural signatures.
+#
+# @example Basic usage
+#   template = File.read("template.rb")
+#   destination = File.read("destination.rb")
+#   merger = Prism::Merge::SmartMerger.new(template, destination)
+#   result = merger.merge
+#
+# @example With debug information
+#   merger = Prism::Merge::SmartMerger.new(template, destination)
+#   debug_result = merger.merge_with_debug
+#   puts debug_result[:debug]
+#   puts debug_result[:statistics]
+module Prism
+  # Smart merge system for Ruby files using Prism AST analysis.
+  # Provides intelligent merging by understanding Ruby code structure
+  # rather than treating files as plain text.
+  #
+  # @see SmartMerger Main entry point for merge operations
+  # @see FileAligner Identifies matching sections and boundaries
+  # @see ConflictResolver Resolves content within boundaries
+  module Merge
+    # Base error class for Prism::Merge
+    class Error < StandardError; end
+
+    # Raised when the template/destination file has parsing errors
+    class ParseError < Error
+      # @return [String] The content that failed to parse
+      attr_reader :content
+
+      # @return [Prism::ParseResult] The Prism parse result containing error details
+      attr_reader :parse_result
+
+      # @param message [String] Error message
+      # @param content [String] The Ruby source that failed to parse
+      # @param parse_result [Prism::ParseResult] Parse result with error information
+      def initialize(message, content:, parse_result:)
+        super(message)
+        @content = content
+        @parse_result = parse_result
+      end
+    end
+
+    # Raised when the template file has syntax errors.
+    #
+    # @example Handling template parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue TemplateParseError => e
+    #     puts "Template syntax error: #{e.message}"
+    #     e.parse_result.errors.each do |error|
+    #       puts "  #{error.message}"
+    #     end
+    #   end
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file has syntax errors.
+    #
+    # @example Handling destination parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue DestinationParseError => e
+    #     puts "Destination syntax error: #{e.message}"
+    #     e.parse_result.errors.each do |error|
+    #       puts "  #{error.message}"
+    #     end
+    #   end
+    class DestinationParseError < ParseError; end
+
+    autoload :FileAnalysis, "prism/merge/file_analysis"
+    autoload :MergeResult, "prism/merge/merge_result"
+    autoload :FileAligner, "prism/merge/file_aligner"
+    autoload :ConflictResolver, "prism/merge/conflict_resolver"
+    autoload :SmartMerger, "prism/merge/smart_merger"
+  end
+end
+
+Prism::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/prism-merge.rb

@@ -0,0 +1,4 @@
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "prism/merge"