prism-merge 1.0.3 → 1.1.0

data/lib/prism/merge/freeze_node.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Prism
+  module Merge
+    # Wrapper to represent freeze blocks as first-class nodes.
+    # A freeze block is a section marked with freeze/unfreeze comment markers that
+    # should be preserved from the destination during merges.
+    #
+    # While freeze blocks are delineated by comment markers, they are conceptually
+    # different from CommentNode and do not inherit from it because:
+    # - FreezeNode is a *structural directive* that contains code and/or comments
+    # - CommentNode represents *pure documentation* with no structural significance
+    # - FreezeNode can contain Ruby code nodes (methods, constants, etc.)
+    # - CommentNode only contains comments
+    # - Their signatures need different semantics for merge matching
+    #
+    # Freeze blocks can contain other nodes (methods, classes, etc.) and those
+    # nodes remain as separate entities within the block for analysis purposes,
+    # but the entire freeze block is treated as an atomic unit during merging.
+    #
+    # @example Freeze block with mixed content
+    #   # prism-merge:freeze
+    #   # Custom documentation
+    #   CUSTOM_CONFIG = { key: "secret" }
+    #   def custom_method
+    #     # ...
+    #   end
+    #   # prism-merge:unfreeze
+    class FreezeNode
+      # Error raised when a freeze block has invalid structure
+      class InvalidStructureError < StandardError
+        attr_reader :start_line, :end_line, :unclosed_nodes
+
+        def initialize(message, start_line: nil, end_line: nil, unclosed_nodes: [])
+          super(message)
+          @start_line = start_line
+          @end_line = end_line
+          @unclosed_nodes = unclosed_nodes
+        end
+      end
+
+      attr_reader :start_line, :end_line, :content, :nodes, :start_marker, :end_marker
+
+      # @param start_line [Integer] Line number of freeze marker
+      # @param end_line [Integer] Line number of unfreeze marker
+      # @param analysis [FileAnalysis] The file analysis containing this block
+      # @param nodes [Array<Prism::Node>] Nodes fully contained within the freeze block
+      # @param overlapping_nodes [Array<Prism::Node>] All nodes that overlap with freeze block (for validation)
+      # @param start_marker [String, nil] The freeze start marker text
+      # @param end_marker [String, nil] The freeze end marker text
+      def initialize(start_line:, end_line:, analysis:, nodes: [], overlapping_nodes: nil, start_marker: nil, end_marker: nil)
+        @start_line = start_line
+        @end_line = end_line
+        @analysis = analysis
+        @nodes = nodes
+        @overlapping_nodes = overlapping_nodes || nodes
+        @start_marker = start_marker
+        @end_marker = end_marker
+
+        # Extract content for the entire block
+        @content = (start_line..end_line).map { |ln| analysis.line_at(ln) }.join
+
+        # Validate structure
+        validate_structure!
+      end
+
+      # Returns a location-like object for compatibility with Prism nodes
+      def location
+        @location ||= Location.new(@start_line, @end_line)
+      end
+
+      # Returns the freeze block content
+      def slice
+        @content
+      end
+
+      # Simple location struct for compatibility
+      Location = Struct.new(:start_line, :end_line) do
+        def cover?(line)
+          (start_line..end_line).cover?(line)
+        end
+      end
+
+      # Returns a stable signature for this freeze block
+      # Signature includes the normalized content to detect changes
+      def signature
+        normalized = (@start_line..@end_line).map do |ln|
+          @analysis.normalized_line(ln)
+        end.compact.join("\n")
+
+        [:FreezeNode, normalized]
+      end
+
+      # Check if this is a freeze node (always true for FreezeNode)
+      def freeze_node?
+        true
+      end
+
+      # String representation for debugging
+      def inspect
+        "#<Prism::Merge::FreezeNode lines=#{@start_line}..#{@end_line} nodes=#{@nodes.length}>"
+      end
+
+      private
+
+      # Validate that the freeze block has proper structure:
+      # - All nodes must be either fully contained or fully outside
+      # - No partial overlaps allowed (a node cannot start before and end inside, or vice versa)
+      def validate_structure!
+        unclosed = []
+
+        # Check all overlapping nodes
+        @overlapping_nodes.each do |node|
+          node_start = node.location.start_line
+          node_end = node.location.end_line
+
+          # Check if node is fully contained (valid)
+          fully_contained = node_start >= @start_line && node_end <= @end_line
+
+          # Check if node completely encompasses the freeze block
+          # This is only valid for ClassNode/ModuleNode (freeze blocks at class/module body level)
+          # For other nodes (methods, etc.), this is invalid
+          encompasses = node_start < @start_line && node_end > @end_line
+          valid_encompass = encompasses && (node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode))
+
+          # Check if node partially overlaps (invalid - unclosed/incomplete structure)
+          partially_overlaps = !fully_contained && !encompasses &&
+            ((node_start < @start_line && node_end >= @start_line) ||
+             (node_start <= @end_line && node_end > @end_line))
+
+          # Invalid if: partial overlap OR if a non-class/module node encompasses the freeze block
+          if partially_overlaps || (encompasses && !valid_encompass)
+            unclosed << node
+          end
+        end
+
+        return if unclosed.empty?
+
+        # Build error message with details about unclosed/overlapping nodes
+        node_descriptions = unclosed.map do |node|
+          node_start = node.location.start_line
+          node_end = node.location.end_line
+          overlap_type = if node_start < @start_line
+            "starts before freeze block (line #{node_start}) and ends inside (line #{node_end})"
+          else
+            "starts inside freeze block (line #{node_start}) and ends after (line #{node_end})"
+          end
+          "#{node.class.name.split("::").last} at lines #{node_start}-#{node_end} (#{overlap_type})"
+        end.join(", ")
+
+        raise InvalidStructureError.new(
+          "Freeze block at lines #{@start_line}-#{@end_line} contains incomplete nodes: #{node_descriptions}. " \
+            "A freeze block must fully contain all nodes within it, or be placed between nodes.",
+          start_line: @start_line,
+          end_line: @end_line,
+          unclosed_nodes: unclosed,
+        )
+      end
+    end
+  end
+end

data/lib/prism/merge/smart_merger.rb

@@ -5,7 +5,10 @@ module Prism
     # 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:
+    # SmartMerger provides flexible configuration for different merge scenarios.
+    # When matching class or module definitions are found in both files, the merger
+    # automatically performs recursive merging of their bodies, intelligently combining
+    # nested methods, constants, and other definitions.
     #
     # @example Basic merge (destination customizations preserved)
     #   merger = SmartMerger.new(template_content, dest_content)
@@ -86,6 +89,10 @@ module Prism
       #   - `true` - Add template-only nodes to result.
       #     Use when template has new required constants/methods to add.
       #
+      # @param freeze_token [String] Token to use for freeze block markers.
+      #   Default: "prism-merge" (looks for # prism-merge:freeze / # prism-merge:unfreeze)
+      #   Freeze blocks preserve destination content unchanged during merge.
+      #
       # @raise [TemplateParseError] If template has syntax errors
       # @raise [DestinationParseError] If destination has syntax errors
       #
@@ -124,13 +131,14 @@ module Prism
       #     destination,
       #     signature_generator: sig_gen
       #   )
-      def initialize(template_content, dest_content, signature_generator: nil, signature_match_preference: :destination, add_template_only_nodes: false)
+      def initialize(template_content, dest_content, signature_generator: nil, signature_match_preference: :destination, add_template_only_nodes: false, freeze_token: FileAnalysis::DEFAULT_FREEZE_TOKEN)
         @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)
+        @freeze_token = freeze_token
+        @template_analysis = FileAnalysis.new(template_content, signature_generator: signature_generator, freeze_token: freeze_token)
+        @dest_analysis = FileAnalysis.new(dest_content, signature_generator: signature_generator, freeze_token: freeze_token)
         @aligner = FileAligner.new(@template_analysis, @dest_analysis)
         @resolver = ConflictResolver.new(
           @template_analysis,
@@ -304,8 +312,15 @@ module Prism
       end
 
       def add_signature_match_from_dest(anchor)
-        # For signature matches, use the configured preference
-        if @signature_match_preference == :template
+        # Find the nodes corresponding to this anchor
+        # Look for nodes that overlap with the anchor range (not just at start line)
+        template_node = find_node_in_range(@template_analysis, anchor.template_start, anchor.template_end)
+        dest_node = find_node_in_range(@dest_analysis, anchor.dest_start, anchor.dest_end)
+
+        # Check if this is a class or module that should be recursively merged
+        if should_merge_recursively?(template_node, dest_node)
+          merge_node_body_recursively(template_node, dest_node, anchor)
+        elsif @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)
@@ -342,6 +357,201 @@ module Prism
       def process_boundary(boundary)
         @resolver.resolve(boundary, @result)
       end
+
+      # Find a node that overlaps with the given line range.
+      # This handles cases where anchors include leading comments (e.g., magic comments).
+      #
+      # @param analysis [FileAnalysis] The file analysis to search
+      # @param start_line [Integer] Start line of the range
+      # @param end_line [Integer] End line of the range
+      # @return [Prism::Node, nil] The first node that overlaps with the range, or nil if none found
+      def find_node_in_range(analysis, start_line, end_line)
+        # Find a node that overlaps with the range
+        analysis.statements.find do |stmt|
+          # Check if node overlaps with the range
+          stmt.location.start_line <= end_line && stmt.location.end_line >= start_line
+        end
+      end
+
+      # Find the node at a specific line in the analysis (deprecated - use find_node_in_range)
+      # @deprecated Use {#find_node_in_range} instead for better handling of leading comments
+      # @param analysis [FileAnalysis] The file analysis to search
+      # @param line_num [Integer] The line number to find a node at
+      # @return [Prism::Node, nil] The node at that line, or nil if none found
+      def find_node_at_line(analysis, line_num)
+        analysis.statements.find do |stmt|
+          line_num.between?(stmt.location.start_line, stmt.location.end_line)
+        end
+      end
+
+      # Determines if two matching nodes should be recursively merged.
+      #
+      # Recursive merge is performed for matching class/module definitions to intelligently
+      # combine their body contents (nested methods, constants, etc.). This allows template
+      # updates to class internals to be merged with destination customizations.
+      #
+      # @param template_node [Prism::Node, nil] Node from template file
+      # @param dest_node [Prism::Node, nil] Node from destination file
+      # @return [Boolean] true if nodes should be recursively merged
+      #
+      # @note Recursive merge is NOT performed for:
+      #   - Conditional nodes (if/unless) - treated as atomic units
+      #   - Classes/modules containing freeze blocks - frozen content would be lost
+      #   - Nodes of different types
+      def should_merge_recursively?(template_node, dest_node)
+        return false unless template_node && dest_node
+
+        is_class_or_module = (template_node.is_a?(Prism::ClassNode) && dest_node.is_a?(Prism::ClassNode)) ||
+          (template_node.is_a?(Prism::ModuleNode) && dest_node.is_a?(Prism::ModuleNode))
+
+        return false unless is_class_or_module
+
+        # Don't recursively merge if either node contains freeze blocks
+        # (they would be lost in the nested merge since we pass freeze_token: nil)
+        return false if node_contains_freeze_blocks?(template_node)
+        return false if node_contains_freeze_blocks?(dest_node)
+
+        true
+      end
+
+      # Check if a node's body contains freeze block markers.
+      #
+      # @param node [Prism::Node] The node to check
+      # @return [Boolean] true if the node's body contains freeze block comments
+      # @api private
+      def node_contains_freeze_blocks?(node)
+        return false unless @freeze_token
+        return false unless node.body
+
+        # Check if any comments in the node's range contain freeze markers
+        freeze_pattern = /#\s*#{Regexp.escape(@freeze_token)}:(freeze|unfreeze)/i
+
+        node_start = node.location.start_line
+        node_end = node.location.end_line
+
+        @template_analysis.parse_result.comments.any? do |comment|
+          comment_line = comment.location.start_line
+          comment_line > node_start && comment_line < node_end && comment.slice.match?(freeze_pattern)
+        end || @dest_analysis.parse_result.comments.any? do |comment|
+          comment_line = comment.location.start_line
+          comment_line > node_start && comment_line < node_end && comment.slice.match?(freeze_pattern)
+        end
+      end
+
+      # Recursively merges the body of matching class or module nodes.
+      #
+      # This method extracts the body content (everything between the class/module
+      # declaration and the closing 'end'), creates a new nested SmartMerger to merge
+      # those bodies, and then reassembles the complete class/module with the merged body.
+      #
+      # @param template_node [Prism::ClassNode, Prism::ModuleNode] Class/module from template
+      # @param dest_node [Prism::ClassNode, Prism::ModuleNode] Class/module from destination
+      # @param anchor [FileAligner::Anchor] The anchor representing this match
+      #
+      # @note The nested merger is configured with:
+      #   - Same signature_generator, signature_match_preference, and add_template_only_nodes
+      #   - freeze_token: nil (freeze blocks not processed in nested context)
+      #
+      # @api private
+      def merge_node_body_recursively(template_node, dest_node, anchor)
+        # Extract the body source for both nodes
+        template_body = extract_node_body(template_node, @template_analysis)
+        dest_body = extract_node_body(dest_node, @dest_analysis)
+
+        # Recursively merge the bodies
+        body_merger = SmartMerger.new(
+          template_body,
+          dest_body,
+          signature_generator: @template_analysis.instance_variable_get(:@signature_generator),
+          signature_match_preference: @signature_match_preference,
+          add_template_only_nodes: @add_template_only_nodes,
+          freeze_token: nil,  # Don't process freeze blocks in nested context
+        )
+        merged_body = body_merger.merge.rstrip
+
+        # Add the opening line (class/module declaration) with leading comments
+        source_analysis = (@signature_match_preference == :template) ? @template_analysis : @dest_analysis
+        source_node = (@signature_match_preference == :template) ? template_node : dest_node
+        source_anchor_start = (@signature_match_preference == :template) ? anchor.template_start : anchor.dest_start
+
+        # Add leading comments
+        (source_anchor_start...source_node.location.start_line).each do |line_num|
+          line = source_analysis.line_at(line_num)
+          @result.add_line(
+            line.chomp,
+            decision: MergeResult::DECISION_REPLACED,
+            template_line: ((@signature_match_preference == :template) ? line_num : nil),
+            dest_line: ((@signature_match_preference == :destination) ? line_num : nil),
+          )
+        end
+
+        # Add the class/module opening line
+        opening_line = source_analysis.line_at(source_node.location.start_line)
+        @result.add_line(
+          opening_line.chomp,
+          decision: MergeResult::DECISION_REPLACED,
+          template_line: ((@signature_match_preference == :template) ? source_node.location.start_line : nil),
+          dest_line: ((@signature_match_preference == :destination) ? source_node.location.start_line : nil),
+        )
+
+        # Add the merged body (indented appropriately)
+        merged_body.lines.each do |line|
+          @result.add_line(
+            line.chomp,
+            decision: MergeResult::DECISION_REPLACED,
+            template_line: nil,
+            dest_line: nil,
+          )
+        end
+
+        # Add the closing 'end'
+        end_line = source_analysis.line_at(source_node.location.end_line)
+        @result.add_line(
+          end_line.chomp,
+          decision: MergeResult::DECISION_REPLACED,
+          template_line: ((@signature_match_preference == :template) ? source_node.location.end_line : nil),
+          dest_line: ((@signature_match_preference == :destination) ? source_node.location.end_line : nil),
+        )
+      end
+
+      # Extracts the body content of a node (without declaration and closing 'end').
+      #
+      # For class/module nodes, extracts content between the declaration line and the
+      # closing 'end'. For conditional nodes, extracts the statements within the condition.
+      #
+      # @param node [Prism::Node] The node to extract body from
+      # @param analysis [FileAnalysis] The file analysis containing the node
+      # @return [String] The extracted body content
+      #
+      # @note Handles different node types:
+      #   - ClassNode/ModuleNode: Uses node.body (StatementsNode)
+      #   - IfNode/UnlessNode: Uses node.statements (StatementsNode)
+      #
+      # @api private
+      def extract_node_body(node, analysis)
+        # Get the statements node based on node type
+        statements_node = if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+          node.body
+        elsif node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
+          node.statements
+        end
+
+        return "" unless statements_node&.is_a?(Prism::StatementsNode)
+
+        body_statements = statements_node.body
+        return "" if body_statements.empty?
+
+        # Get the line range of the body (between opening line and end)
+        first_stmt_line = body_statements.first.location.start_line
+        last_stmt_line = body_statements.last.location.end_line
+
+        # Extract the source lines for the body
+        lines = []
+        (first_stmt_line..last_stmt_line).each do |line_num|
+          lines << analysis.line_at(line_num).chomp
+        end
+        lines.join("\n") + "\n"
+      end
     end
   end
 end

data/lib/prism/merge/version.rb

@@ -5,7 +5,7 @@ module Prism
     # Version information for Prism::Merge
     module Version
       # Current version of the prism-merge gem
-      VERSION = "1.0.3"
+      VERSION = "1.1.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/prism/merge.rb

@@ -80,6 +80,8 @@ module Prism
     #   end
     class DestinationParseError < ParseError; end
 
+    autoload :DebugLogger, "prism/merge/debug_logger"
+    autoload :FreezeNode, "prism/merge/freeze_node"
     autoload :FileAnalysis, "prism/merge/file_analysis"
     autoload :MergeResult, "prism/merge/merge_result"
     autoload :FileAligner, "prism/merge/file_aligner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prism-merge
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -252,8 +252,10 @@ files:
 - lib/prism-merge.rb
 - lib/prism/merge.rb
 - lib/prism/merge/conflict_resolver.rb
+- lib/prism/merge/debug_logger.rb
 - lib/prism/merge/file_aligner.rb
 - lib/prism/merge/file_analysis.rb
+- lib/prism/merge/freeze_node.rb
 - lib/prism/merge/merge_result.rb
 - lib/prism/merge/smart_merger.rb
 - lib/prism/merge/version.rb
@@ -263,10 +265,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://prism-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/prism-merge/tree/v1.0.3
-  changelog_uri: https://github.com/kettle-rb/prism-merge/blob/v1.0.3/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/prism-merge/tree/v1.1.0
+  changelog_uri: https://github.com/kettle-rb/prism-merge/blob/v1.1.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/prism-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/prism-merge/1.0.3
+  documentation_uri: https://www.rubydoc.info/gems/prism-merge/1.1.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/prism-merge/wiki
   news_uri: https://www.railsbling.com/tags/prism-merge