rbs-merge 1.0.0

data/lib/rbs/merge/freeze_node.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # Wrapper to represent freeze blocks as first-class nodes in RBS files.
+    # A freeze block is a section marked with freeze/unfreeze comment markers that
+    # should be preserved from the destination during merges.
+    #
+    # Inherits from Ast::Merge::FreezeNodeBase for shared functionality including
+    # the Location struct, InvalidStructureError, and configurable marker patterns.
+    #
+    # Uses the `:hash_comment` pattern type by default for RBS type signature files.
+    #
+    # @example Freeze block in RBS
+    #   # rbs-merge:freeze
+    #   # Custom type definitions
+    #   type custom_config = { key: String, value: untyped }
+    #   # rbs-merge:unfreeze
+    #
+    # @example Freeze block with reason
+    #   # rbs-merge:freeze Project-specific types
+    #   type project_result = success | failure
+    #   # rbs-merge:unfreeze
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      # Inherit InvalidStructureError from base class
+      InvalidStructureError = Ast::Merge::FreezeNodeBase::InvalidStructureError
+
+      # Inherit Location from base class
+      Location = Ast::Merge::FreezeNodeBase::Location
+
+      # @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<RBS::AST::Declarations::Base, RBS::AST::Members::Base>] Nodes fully contained within the freeze block
+      # @param overlapping_nodes [Array] 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
+      # @param pattern_type [Symbol] Pattern type for marker matching (defaults to :hash_comment)
+      def initialize(start_line:, end_line:, analysis:, nodes: [], overlapping_nodes: nil, start_marker: nil, end_marker: nil, pattern_type: Ast::Merge::FreezeNodeBase::DEFAULT_PATTERN)
+        super(
+          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,
+          pattern_type: pattern_type
+        )
+
+        # Validate structure
+        validate_structure!
+      end
+
+      # Returns a stable signature for this freeze block
+      # Signature includes the normalized content to detect changes
+      # @return [Array] Signature array
+      def signature
+        normalized = (@start_line..@end_line).map do |ln|
+          @analysis.normalized_line(ln)
+        end.compact.join("\n")
+
+        [:FreezeNode, normalized]
+      end
+
+      # String representation for debugging
+      # @return [String]
+      def inspect
+        "#<Rbs::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
+      def validate_structure!
+        unclosed = []
+
+        @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 valid for container nodes like classes/modules
+          encompasses = node_start < @start_line && node_end > @end_line
+
+          # Check if node is fully outside (valid)
+          fully_outside = node_end < @start_line || node_start > @end_line
+
+          # If none of the above, it's a partial overlap (invalid)
+          next if fully_contained || encompasses || fully_outside
+
+          unclosed << node
+        end
+
+        return if unclosed.empty?
+
+        node_names = unclosed.map do |n|
+          name = n.respond_to?(:name) ? n.name.to_s : n.class.name.split("::").last
+          "#{name} (lines #{n.location.start_line}-#{n.location.end_line})"
+        end.join(", ")
+
+        raise InvalidStructureError.new(
+          "Freeze block at lines #{@start_line}-#{@end_line} has partial overlap with: #{node_names}. " \
+            "Freeze blocks must fully contain declarations or be fully contained within them.",
+          start_line: @start_line,
+          end_line: @end_line,
+          unclosed_nodes: unclosed,
+        )
+      end
+    end
+  end
+end

data/lib/rbs/merge/merge_result.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # Result container for RBS file merge operations.
+    # Inherits from Ast::Merge::MergeResultBase for shared functionality.
+    #
+    # Tracks merged content, decisions made during merge, and provides
+    # methods to reconstruct the final merged RBS file.
+    #
+    # @example Basic usage
+    #   result = MergeResult.new(template_analysis, dest_analysis)
+    #   result.add_from_template(0)
+    #   result.add_from_destination(1)
+    #   merged_content = result.to_s
+    #
+    # @see Ast::Merge::MergeResultBase
+    class MergeResult < Ast::Merge::MergeResultBase
+      # Decision indicating content was preserved from a freeze block
+      # @return [Symbol]
+      DECISION_FREEZE_BLOCK = :freeze_block
+
+      # Decision indicating content came from the template
+      # @return [Symbol]
+      DECISION_TEMPLATE = :template
+
+      # Decision indicating content came from the destination (customization preserved)
+      # @return [Symbol]
+      DECISION_DESTINATION = :destination
+
+      # Decision indicating content was added from template (new in template)
+      # @return [Symbol]
+      DECISION_ADDED = :added
+
+      # Decision indicating content was recursively merged
+      # @return [Symbol]
+      DECISION_RECURSIVE = :recursive
+
+      # Initialize a new merge result
+      # @param template_analysis [FileAnalysis] Analysis of the template file
+      # @param dest_analysis [FileAnalysis] Analysis of the destination file
+      def initialize(template_analysis, dest_analysis)
+        super(template_analysis: template_analysis, dest_analysis: dest_analysis)
+      end
+
+      # Add content from the template at the given statement index
+      # @param index [Integer] Statement index in template
+      # @param decision [Symbol] Decision type (default: DECISION_TEMPLATE)
+      # @return [void]
+      def add_from_template(index, decision: DECISION_TEMPLATE)
+        statement = @template_analysis.statements[index]
+        return unless statement
+
+        lines = extract_lines(statement, @template_analysis)
+        @lines.concat(lines)
+        @decisions << {decision: decision, source: :template, index: index, lines: lines.length}
+      end
+
+      # Add content from the destination at the given statement index
+      # @param index [Integer] Statement index in destination
+      # @param decision [Symbol] Decision type (default: DECISION_DESTINATION)
+      # @return [void]
+      def add_from_destination(index, decision: DECISION_DESTINATION)
+        statement = @dest_analysis.statements[index]
+        return unless statement
+
+        lines = extract_lines(statement, @dest_analysis)
+        @lines.concat(lines)
+        @decisions << {decision: decision, source: :destination, index: index, lines: lines.length}
+      end
+
+      # Add content from a freeze block
+      # @param freeze_node [FreezeNode] The freeze block to add
+      # @return [void]
+      def add_freeze_block(freeze_node)
+        lines = (freeze_node.start_line..freeze_node.end_line).map do |ln|
+          @dest_analysis.line_at(ln)
+        end
+        @lines.concat(lines)
+        @decisions << {
+          decision: DECISION_FREEZE_BLOCK,
+          source: :destination,
+          start_line: freeze_node.start_line,
+          end_line: freeze_node.end_line,
+          lines: lines.length,
+        }
+      end
+
+      # Add recursively merged content
+      # @param merged_content [String] The merged content string
+      # @param template_index [Integer] Template statement index
+      # @param dest_index [Integer] Destination statement index
+      # @return [void]
+      def add_recursive_merge(merged_content, template_index:, dest_index:)
+        # Split without trailing newlines for consistency with other methods
+        lines = merged_content.split("\n", -1)
+        # Remove trailing empty element if content ended with newline
+        lines.pop if lines.last == ""
+        @lines.concat(lines)
+        @decisions << {
+          decision: DECISION_RECURSIVE,
+          source: :merged,
+          template_index: template_index,
+          dest_index: dest_index,
+          lines: lines.length,
+        }
+      end
+
+      # Add raw content lines
+      # @param lines [Array<String>] Lines to add
+      # @param decision [Symbol] Decision type
+      # @return [void]
+      def add_raw(lines, decision:)
+        @lines.concat(lines)
+        @decisions << {decision: decision, source: :raw, lines: lines.length}
+      end
+
+      # Convert the merged result to a string
+      # @return [String] The merged RBS content
+      def to_s
+        return "" if @lines.empty?
+
+        # Lines are stored without trailing newlines, so join with newlines
+        result = @lines.join("\n")
+        # Ensure file ends with newline if content is non-empty
+        result += "\n" unless result.end_with?("\n")
+        result
+      end
+
+      # Check if any content has been added
+      # @return [Boolean]
+      def empty?
+        @lines.empty?
+      end
+
+      # Get summary of merge decisions
+      # @return [Hash] Summary with counts by decision type
+      def summary
+        counts = @decisions.group_by { |d| d[:decision] }.transform_values(&:count)
+        {
+          total_decisions: @decisions.length,
+          total_lines: @lines.length,
+          by_decision: counts,
+        }
+      end
+
+      private
+
+      # Extract lines for a statement from analysis
+      # @param statement [Object] The statement (declaration, member, or FreezeNode)
+      # @param analysis [FileAnalysis] The file analysis
+      # @return [Array<String>] Lines for the statement
+      def extract_lines(statement, analysis)
+        if statement.is_a?(FreezeNode)
+          (statement.start_line..statement.end_line).map { |ln| analysis.line_at(ln) }
+        else
+          start_line = statement.location.start_line
+          end_line = statement.location.end_line
+
+          # Include leading comment if present
+          if statement.respond_to?(:comment) && statement.comment
+            comment_start = statement.comment.location.start_line
+            start_line = comment_start if comment_start < start_line
+          end
+
+          (start_line..end_line).map { |ln| analysis.line_at(ln) }
+        end
+      end
+    end
+  end
+end

data/lib/rbs/merge/smart_merger.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # Orchestrates the smart merge process for RBS type signature files.
+    # Uses FileAnalysis, FileAligner, ConflictResolver, and MergeResult to
+    # merge two RBS files intelligently.
+    #
+    # SmartMerger provides flexible configuration for different merge scenarios.
+    # When matching class or module definitions are found in both files, the merger
+    # can perform recursive merging of their members.
+    #
+    # @example Basic merge (destination customizations preserved)
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   result = merger.merge
+    #
+    # @example Template updates win
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     preference: :template,
+    #     add_template_only_nodes: true
+    #   )
+    #   result = merger.merge
+    #
+    # @example Custom signature matching
+    #   sig_gen = ->(node) { [:decl, node.name.to_s] }
+    #   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 RBS file merging.
+      #
+      # @param template_content [String] Template RBS source code
+      # @param dest_content [String] Destination RBS source code
+      #
+      # @param signature_generator [Proc, nil] Optional proc to generate custom node signatures.
+      #   The proc receives an RBS declaration and should return one of:
+      #   - An array representing the node's signature
+      #   - `nil` to indicate the node should have no signature
+      #   - The original node to fall through to default signature computation
+      #
+      # @param preference [Symbol] Controls which version to use when nodes
+      #   have matching signatures but different content:
+      #   - `:destination` (default) - Use destination version (preserves customizations)
+      #   - `:template` - Use template version (applies updates)
+      #
+      # @param add_template_only_nodes [Boolean] Controls whether to add nodes that only
+      #   exist in template:
+      #   - `false` (default) - Skip template-only nodes
+      #   - `true` - Add template-only nodes to result
+      #
+      # @param freeze_token [String] Token to use for freeze block markers.
+      #   Default: "rbs-merge" (looks for # rbs-merge:freeze / # rbs-merge:unfreeze)
+      #
+      # @param max_recursion_depth [Integer, Float] Maximum depth for recursive body merging.
+      #   Default: Float::INFINITY (no limit)
+      #
+      # @raise [TemplateParseError] If template has syntax errors
+      # @raise [DestinationParseError] If destination has syntax errors
+      def initialize(
+        template_content,
+        dest_content,
+        signature_generator: nil,
+        preference: :destination,
+        add_template_only_nodes: false,
+        freeze_token: FileAnalysis::DEFAULT_FREEZE_TOKEN,
+        max_recursion_depth: Float::INFINITY
+      )
+        @preference = preference
+        @add_template_only_nodes = add_template_only_nodes
+        @max_recursion_depth = max_recursion_depth
+
+        # Parse template
+        begin
+          @template_analysis = FileAnalysis.new(
+            template_content,
+            freeze_token: freeze_token,
+            signature_generator: signature_generator,
+          )
+        rescue RBS::ParsingError => e
+          raise TemplateParseError.new([e])
+        end
+
+        # Parse destination
+        begin
+          @dest_analysis = FileAnalysis.new(
+            dest_content,
+            freeze_token: freeze_token,
+            signature_generator: signature_generator,
+          )
+        rescue RBS::ParsingError => e
+          raise DestinationParseError.new([e])
+        end
+
+        @aligner = FileAligner.new(@template_analysis, @dest_analysis)
+        @resolver = ConflictResolver.new(
+          preference: @preference,
+          template_analysis: @template_analysis,
+          dest_analysis: @dest_analysis,
+        )
+        @result = MergeResult.new(@template_analysis, @dest_analysis)
+      end
+
+      # Perform the merge operation
+      #
+      # @return [String] The merged content as a string
+      def merge
+        merge_result.to_s
+      end
+
+      # Perform the merge operation and return the full result object
+      #
+      # @return [MergeResult] The merge result containing merged content
+      def merge_result
+        return @merge_result if @merge_result
+
+        @merge_result = DebugLogger.time("SmartMerger#merge") do
+          alignment = @aligner.align
+
+          DebugLogger.debug("Alignment complete", {
+            total_entries: alignment.size,
+            matches: alignment.count { |e| e[:type] == :match },
+            template_only: alignment.count { |e| e[:type] == :template_only },
+            dest_only: alignment.count { |e| e[:type] == :dest_only },
+          })
+
+          process_alignment(alignment)
+          @result
+        end
+      end
+
+      private
+
+      # Process alignment entries and build result
+      # @param alignment [Array<Hash>] Alignment entries
+      # @return [void]
+      def process_alignment(alignment)
+        alignment.each do |entry|
+          case entry[:type]
+          when :match
+            process_match(entry)
+          when :template_only
+            process_template_only(entry)
+          when :dest_only
+            process_dest_only(entry)
+          end
+        end
+      end
+
+      # Process a matched declaration pair
+      # @param entry [Hash] Alignment entry
+      # @return [void]
+      def process_match(entry)
+        resolution = @resolver.resolve(
+          entry[:template_decl],
+          entry[:dest_decl],
+          template_index: entry[:template_index],
+          dest_index: entry[:dest_index],
+        )
+
+        case resolution[:source]
+        when :template
+          @result.add_from_template(entry[:template_index], decision: resolution[:decision])
+        when :destination
+          if entry[:dest_decl].is_a?(FreezeNode)
+            @result.add_freeze_block(entry[:dest_decl])
+          else
+            @result.add_from_destination(entry[:dest_index], decision: resolution[:decision])
+          end
+        when :recursive
+          process_recursive_merge(entry, resolution)
+        end
+      end
+
+      # Process a template-only declaration
+      # @param entry [Hash] Alignment entry
+      # @return [void]
+      def process_template_only(entry)
+        return unless @add_template_only_nodes
+
+        @result.add_from_template(entry[:template_index], decision: MergeResult::DECISION_ADDED)
+      end
+
+      # Process a destination-only declaration
+      # @param entry [Hash] Alignment entry
+      # @return [void]
+      def process_dest_only(entry)
+        if entry[:dest_decl].is_a?(FreezeNode)
+          @result.add_freeze_block(entry[:dest_decl])
+        else
+          @result.add_from_destination(entry[:dest_index], decision: MergeResult::DECISION_DESTINATION)
+        end
+      end
+
+      # Process recursive merge for container declarations
+      # @param entry [Hash] Alignment entry
+      # @param resolution [Hash] Resolution info
+      # @return [void]
+      def process_recursive_merge(entry, resolution)
+        template_decl = resolution[:template_declaration]
+        dest_decl = resolution[:dest_declaration]
+
+        # For now, just use the destination version for complex recursive merges
+        # A full recursive implementation would merge members individually
+        merged_content = reconstruct_declaration_with_merged_members(
+          template_decl,
+          dest_decl,
+          entry[:template_index],
+          entry[:dest_index],
+        )
+
+        @result.add_recursive_merge(
+          merged_content,
+          template_index: entry[:template_index],
+          dest_index: entry[:dest_index],
+        )
+      end
+
+      # Reconstruct a declaration with merged members
+      # @param template_decl [Object] Template declaration
+      # @param dest_decl [Object] Destination declaration
+      # @param template_index [Integer] Template index
+      # @param dest_index [Integer] Destination index
+      # @return [String] Merged declaration source
+      def reconstruct_declaration_with_merged_members(template_decl, dest_decl, template_index, dest_index)
+        # Choose which declaration to use based on preference
+        decl = (@preference == :template) ? template_decl : dest_decl
+        analysis = (@preference == :template) ? @template_analysis : @dest_analysis
+
+        start_line = decl.location.start_line
+        end_line = decl.location.end_line
+
+        # Include leading comment if present
+        if decl.respond_to?(:comment) && decl.comment
+          comment_start = decl.comment.location.start_line
+          start_line = comment_start if comment_start < start_line
+        end
+
+        (start_line..end_line).map { |ln| analysis.line_at(ln) }.join("\n") + "\n"
+      end
+    end
+  end
+end

data/lib/rbs/merge/version.rb

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

data/lib/rbs/merge.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# External gems
+require "rbs"
+require "version_gem"
+require "set"
+
+# Shared merge infrastructure
+require "ast/merge"
+
+# This gem
+require_relative "merge/version"
+
+module Rbs
+  module Merge
+    # Base error class for rbs-merge errors
+    # Inherits from Ast::Merge::Error for consistency across merge gems.
+    # @api public
+    class Error < Ast::Merge::Error; end
+
+    # Raised when an RBS file has parsing errors.
+    # Inherits from Ast::Merge::ParseError for consistency across merge gems.
+    #
+    # @example Handling parse errors
+    #   begin
+    #     analysis = FileAnalysis.new(rbs_content)
+    #   rescue ParseError => e
+    #     puts "RBS syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error}" }
+    #   end
+    #
+    # @api public
+    class ParseError < Ast::Merge::ParseError
+      # @param message [String, nil] Error message (auto-generated if nil)
+      # @param content [String, nil] The RBS source that failed to parse
+      # @param errors [Array] Parse errors from RBS
+      def initialize(message = nil, content: nil, errors: [])
+        super(message, errors: errors, content: content)
+      end
+    end
+
+    # Raised when the template RBS 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.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    #
+    # @api public
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination RBS 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.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    #
+    # @api public
+    class DestinationParseError < ParseError; end
+
+    autoload :DebugLogger, "rbs/merge/debug_logger"
+    autoload :FreezeNode, "rbs/merge/freeze_node"
+    autoload :MergeResult, "rbs/merge/merge_result"
+    autoload :FileAnalysis, "rbs/merge/file_analysis"
+    autoload :ConflictResolver, "rbs/merge/conflict_resolver"
+    autoload :FileAligner, "rbs/merge/file_aligner"
+    autoload :SmartMerger, "rbs/merge/smart_merger"
+  end
+end
+
+Rbs::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/rbs-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 "rbs/merge"