rbs-merge 1.0.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/rbs/merge/conflict_resolver.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # Resolves conflicts between template and destination declarations.
+    # Determines which version to use when both files have declarations
+    # with matching signatures but different content.
+    #
+    # @example Basic usage
+    #   resolver = ConflictResolver.new(
+    #     preference: :destination,
+    #     template_analysis: template_analysis,
+    #     dest_analysis: dest_analysis
+    #   )
+    #   winner = resolver.resolve(template_decl, dest_decl)
+    class ConflictResolver < ::Ast::Merge::ConflictResolverBase
+      # Initialize a conflict resolver
+      #
+      # @param preference [Symbol] Which version wins on conflict (:template or :destination)
+      # @param template_analysis [FileAnalysis] Analysis of the template file
+      # @param dest_analysis [FileAnalysis] Analysis of the destination file
+      def initialize(preference:, template_analysis:, dest_analysis:)
+        super(
+          strategy: :node,
+          preference: preference,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis
+        )
+      end
+
+      # Resolve a conflict between template and destination declarations
+      #
+      # @param template_decl [Object] Template declaration
+      # @param dest_decl [Object] Destination declaration
+      # @param template_index [Integer] Index in template statements
+      # @param dest_index [Integer] Index in destination statements
+      # @return [Hash] Resolution result with :source and :declaration keys
+      def resolve(template_decl, dest_decl, template_index:, dest_index:)
+        # Freeze blocks always win (they represent protected content)
+        if freeze_node?(dest_decl)
+          return {source: :destination, declaration: dest_decl, decision: DECISION_FREEZE_BLOCK}
+        end
+
+        # Check if declarations are identical
+        if declarations_identical?(template_decl, dest_decl)
+          # Prefer destination to minimize diffs
+          return {source: :destination, declaration: dest_decl, decision: DECISION_DESTINATION}
+        end
+
+        # Check if we should recursively merge (for container types)
+        if can_recursive_merge?(template_decl, dest_decl)
+          return {
+            source: :recursive,
+            template_declaration: template_decl,
+            dest_declaration: dest_decl,
+            decision: DECISION_RECURSIVE,
+          }
+        end
+
+        # Apply preference
+        case @preference
+        when :template
+          {source: :template, declaration: template_decl, decision: DECISION_TEMPLATE}
+        else # :destination (validated in initialize)
+          {source: :destination, declaration: dest_decl, decision: DECISION_DESTINATION}
+        end
+      end
+
+      # Check if two declarations are identical
+      # @param decl1 [Object] First declaration
+      # @param decl2 [Object] Second declaration
+      # @return [Boolean]
+      def declarations_identical?(decl1, decl2)
+        # Use RBS's built-in equality
+        decl1 == decl2
+      end
+
+      # Check if declarations can be recursively merged
+      # @param template_decl [Object] Template declaration
+      # @param dest_decl [Object] Destination declaration
+      # @return [Boolean]
+      def can_recursive_merge?(template_decl, dest_decl)
+        # Only container types can be recursively merged
+        container_types = [
+          RBS::AST::Declarations::Class,
+          RBS::AST::Declarations::Module,
+          RBS::AST::Declarations::Interface,
+        ]
+
+        template_decl.class == dest_decl.class &&
+          container_types.any? { |type| template_decl.is_a?(type) } &&
+          template_decl.respond_to?(:members) &&
+          dest_decl.respond_to?(:members) &&
+          template_decl.members.any? &&
+          dest_decl.members.any?
+      end
+    end
+  end
+end

data/lib/rbs/merge/debug_logger.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # Debug logging utility for RBS merge operations.
+    # Extends Ast::Merge::DebugLogger for shared functionality.
+    #
+    # @example Enable debug logging
+    #   ENV['RBS_MERGE_DEBUG'] = '1'
+    #   # ... perform merge operations ...
+    #
+    # @example Time a block of code
+    #   result = Rbs::Merge::DebugLogger.time("parsing") { parse_file }
+    #
+    # @see Ast::Merge::DebugLogger
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      # RBS-specific configuration
+      self.env_var_name = "RBS_MERGE_DEBUG"
+      self.log_prefix = "[rbs-merge]"
+    end
+  end
+end

data/lib/rbs/merge/file_aligner.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # Aligns declarations between template and destination files by matching signatures.
+    # Produces alignment information used by SmartMerger to combine files.
+    #
+    # @example Basic usage
+    #   aligner = FileAligner.new(template_analysis, dest_analysis)
+    #   alignment = aligner.align
+    #   alignment.each do |entry|
+    #     case entry[:type]
+    #     when :match
+    #       # Both files have this declaration
+    #     when :template_only
+    #       # Only in template
+    #     when :dest_only
+    #       # Only in destination
+    #     end
+    #   end
+    class FileAligner
+      # @return [FileAnalysis] Template file analysis
+      attr_reader :template_analysis
+
+      # @return [FileAnalysis] Destination file analysis
+      attr_reader :dest_analysis
+
+      # Initialize a file aligner
+      #
+      # @param template_analysis [FileAnalysis] Analysis of the template file
+      # @param dest_analysis [FileAnalysis] Analysis of the destination file
+      def initialize(template_analysis, dest_analysis)
+        @template_analysis = template_analysis
+        @dest_analysis = dest_analysis
+      end
+
+      # Perform alignment between template and destination statements
+      #
+      # @return [Array<Hash>] Alignment entries with type, indices, and declarations
+      def align
+        template_statements = @template_analysis.statements
+        dest_statements = @dest_analysis.statements
+
+        # Build signature maps
+        template_by_sig = build_signature_map(template_statements, @template_analysis)
+        dest_by_sig = build_signature_map(dest_statements, @dest_analysis)
+
+        # Track which indices have been matched
+        matched_template = Set.new
+        matched_dest = Set.new
+        alignment = []
+
+        # First pass: find matches by signature
+        template_by_sig.each do |sig, template_indices|
+          next unless dest_by_sig.key?(sig)
+
+          dest_indices = dest_by_sig[sig]
+
+          # Match indices pairwise (first template with first dest, etc.)
+          template_indices.zip(dest_indices).each do |t_idx, d_idx|
+            next unless t_idx && d_idx
+
+            alignment << {
+              type: :match,
+              template_index: t_idx,
+              dest_index: d_idx,
+              signature: sig,
+              template_decl: template_statements[t_idx],
+              dest_decl: dest_statements[d_idx],
+            }
+
+            matched_template << t_idx
+            matched_dest << d_idx
+          end
+        end
+
+        # Second pass: add template-only entries
+        template_statements.each_with_index do |stmt, idx|
+          next if matched_template.include?(idx)
+
+          alignment << {
+            type: :template_only,
+            template_index: idx,
+            dest_index: nil,
+            signature: @template_analysis.signature_at(idx),
+            template_decl: stmt,
+            dest_decl: nil,
+          }
+        end
+
+        # Third pass: add dest-only entries
+        dest_statements.each_with_index do |stmt, idx|
+          next if matched_dest.include?(idx)
+
+          alignment << {
+            type: :dest_only,
+            template_index: nil,
+            dest_index: idx,
+            signature: @dest_analysis.signature_at(idx),
+            template_decl: nil,
+            dest_decl: stmt,
+          }
+        end
+
+        # Sort by appearance order (prefer destination order, then template)
+        sort_alignment(alignment)
+      end
+
+      private
+
+      # Build a map from signatures to statement indices
+      # @param statements [Array] Statements to map
+      # @param analysis [FileAnalysis] File analysis for signature generation
+      # @return [Hash{Array => Array<Integer>}] Signature to indices map
+      def build_signature_map(statements, analysis)
+        map = Hash.new { |h, k| h[k] = [] }
+
+        statements.each_with_index do |_stmt, idx|
+          sig = analysis.signature_at(idx)
+          map[sig] << idx if sig
+        end
+
+        map
+      end
+
+      # Sort alignment entries for output
+      # @param alignment [Array<Hash>] Alignment entries
+      # @return [Array<Hash>] Sorted alignment
+      def sort_alignment(alignment)
+        alignment.sort_by do |entry|
+          case entry[:type]
+          when :match
+            # Sort by destination index for matches
+            [0, entry[:dest_index], entry[:template_index]]
+          when :dest_only
+            # Destination-only items sorted by their index
+            [1, entry[:dest_index], 0]
+          when :template_only
+            # Template-only items at the end, by template index
+            [2, entry[:template_index], 0]
+          else
+            [3, 0, 0]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rbs/merge/file_analysis.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Rbs
+  module Merge
+    # File analysis for RBS type signature files.
+    # Parses RBS source code and extracts declarations, members, and freeze blocks.
+    #
+    # This class provides the foundation for intelligent merging by:
+    # - Parsing RBS files using the official RBS parser
+    # - Extracting top-level declarations (classes, modules, interfaces, type aliases, constants)
+    # - Detecting freeze blocks marked with comment directives
+    # - Generating signatures for matching declarations between files
+    #
+    # @example Basic usage
+    #   analysis = FileAnalysis.new(rbs_source)
+    #   analysis.statements.each do |stmt|
+    #     puts stmt.class
+    #   end
+    #
+    # @example With custom freeze token
+    #   analysis = FileAnalysis.new(source, freeze_token: "my-merge")
+    #   # Looks for: # my-merge:freeze / # my-merge:unfreeze
+    class FileAnalysis
+      include Ast::Merge::FileAnalyzable
+
+      # Default freeze token for identifying freeze blocks
+      # @return [String]
+      DEFAULT_FREEZE_TOKEN = "rbs-merge"
+
+      # @return [RBS::Buffer] The RBS buffer for this file
+      attr_reader :buffer
+
+      # @return [Array<RBS::AST::Directives::Base>] RBS directives (use statements, etc.)
+      attr_reader :directives
+
+      # @return [Array<RBS::AST::Declarations::Base>] Raw declarations from parser
+      attr_reader :declarations
+
+      # Initialize file analysis with RBS parser
+      #
+      # @param source [String] RBS source code to analyze
+      # @param freeze_token [String] Token for freeze block markers (default: "rbs-merge")
+      # @param signature_generator [Proc, nil] Custom signature generator
+      # @raise [RBS::ParsingError] If the source has syntax errors
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil)
+        @source = source
+        @lines = source.split("\n", -1)
+        @freeze_token = freeze_token
+        @signature_generator = signature_generator
+
+        # Parse the RBS source
+        @buffer = RBS::Buffer.new(name: "merge.rbs", content: source)
+        @buffer, @directives, @declarations = DebugLogger.time("FileAnalysis#parse") do
+          RBS::Parser.parse_signature(@buffer)
+        end
+
+        # Extract and integrate all nodes including freeze blocks
+        @statements = extract_and_integrate_all_nodes
+
+        DebugLogger.debug("FileAnalysis initialized", {
+          signature_generator: signature_generator ? "custom" : "default",
+          directives_count: @directives.size,
+          declarations_count: @declarations.size,
+          statements_count: @statements.size,
+          freeze_blocks: freeze_blocks.size,
+        })
+      end
+
+      # Check if parse was successful (RBS parser raises on failure, so always true if we get here)
+      # @return [Boolean]
+      def valid?
+        true
+      end
+
+      # Get all statements (declarations outside freeze blocks + FreezeNodes)
+      # @return [Array<RBS::AST::Declarations::Base, FreezeNode>]
+      attr_reader :statements
+
+      # Compute default signature for a node
+      # @param node [Object] The declaration or FreezeNode
+      # @return [Array, nil] Signature array
+      def compute_node_signature(node)
+        case node
+        when FreezeNode
+          node.signature
+        when RBS::AST::Declarations::Class
+          [:class, node.name.to_s]
+        when RBS::AST::Declarations::Module
+          [:module, node.name.to_s]
+        when RBS::AST::Declarations::Interface
+          [:interface, node.name.to_s]
+        when RBS::AST::Declarations::TypeAlias
+          [:type_alias, node.name.to_s]
+        when RBS::AST::Declarations::Constant
+          [:constant, node.name.to_s]
+        when RBS::AST::Declarations::Global
+          [:global, node.name.to_s]
+        when RBS::AST::Members::MethodDefinition
+          [:method, node.name.to_s, node.kind]
+        when RBS::AST::Members::Alias
+          [:alias, node.new_name.to_s, node.old_name.to_s]
+        when RBS::AST::Members::AttrReader
+          [:attr_reader, node.name.to_s]
+        when RBS::AST::Members::AttrWriter
+          [:attr_writer, node.name.to_s]
+        when RBS::AST::Members::AttrAccessor
+          [:attr_accessor, node.name.to_s]
+        when RBS::AST::Members::Include
+          [:include, node.name.to_s]
+        when RBS::AST::Members::Extend
+          [:extend, node.name.to_s]
+        when RBS::AST::Members::Prepend
+          [:prepend, node.name.to_s]
+        when RBS::AST::Members::InstanceVariable
+          [:ivar, node.name.to_s]
+        when RBS::AST::Members::ClassInstanceVariable
+          [:civar, node.name.to_s]
+        when RBS::AST::Members::ClassVariable
+          [:cvar, node.name.to_s]
+        else
+          # Unknown node type - use class name and location as signature
+          [:unknown, node.class.name, node.location&.start_line]
+        end
+      end
+
+      # Override to detect RBS nodes for signature generator fallthrough
+      # @param value [Object] The value to check
+      # @return [Boolean] true if this is a fallthrough node
+      def fallthrough_node?(value)
+        value.is_a?(RBS::AST::Declarations::Base) ||
+          value.is_a?(RBS::AST::Members::Base) ||
+          value.is_a?(FreezeNode) ||
+          super
+      end
+
+      private
+
+      # Extract all nodes and integrate freeze blocks
+      # @return [Array<Object>] Integrated list of declarations and freeze blocks
+      def extract_and_integrate_all_nodes
+        freeze_markers = find_freeze_markers
+        return @declarations.dup if freeze_markers.empty?
+
+        # Build freeze blocks from markers
+        freeze_block_nodes = build_freeze_blocks(freeze_markers)
+        return @declarations.dup if freeze_block_nodes.empty?
+
+        # Integrate declarations with freeze blocks
+        integrate_nodes_with_freeze_blocks(@declarations, freeze_block_nodes)
+      end
+
+      # Find all freeze markers in the source
+      # @return [Array<Hash>] Array of marker info hashes
+      def find_freeze_markers
+        markers = []
+        # Use shared pattern from Ast::Merge::FreezeNodeBase with our specific token
+        pattern = Ast::Merge::FreezeNodeBase.pattern_for(:hash_comment, @freeze_token)
+
+        @lines.each_with_index do |line, idx|
+          line_num = idx + 1
+          next unless (match = line.match(pattern))
+
+          marker_type = match[1]&.downcase # 'freeze' or 'unfreeze'
+          if marker_type == "freeze"
+            markers << {type: :start, line: line_num, text: line}
+          elsif marker_type == "unfreeze"
+            markers << {type: :end, line: line_num, text: line}
+          end
+        end
+
+        markers
+      end
+
+      # Build freeze blocks from paired markers
+      # @param markers [Array<Hash>] Freeze markers
+      # @return [Array<FreezeNode>] Freeze block nodes
+      def build_freeze_blocks(markers)
+        blocks = []
+        stack = []
+
+        markers.each do |marker|
+          case marker[:type]
+          when :start
+            stack.push(marker)
+          when :end
+            if stack.any?
+              start_marker = stack.pop
+              # Find nodes contained in this freeze block
+              contained_nodes = find_contained_nodes(start_marker[:line], marker[:line])
+              overlapping_nodes = find_overlapping_nodes(start_marker[:line], marker[:line])
+
+              blocks << FreezeNode.new(
+                start_line: start_marker[:line],
+                end_line: marker[:line],
+                analysis: self,
+                nodes: contained_nodes,
+                overlapping_nodes: overlapping_nodes,
+                start_marker: start_marker[:text],
+                end_marker: marker[:text],
+              )
+            else
+              DebugLogger.warning("Unmatched freeze end marker at line #{marker[:line]}")
+            end
+          end
+        end
+
+        stack.each do |unmatched|
+          DebugLogger.warning("Unmatched freeze start marker at line #{unmatched[:line]}")
+        end
+
+        blocks
+      end
+
+      # Find declarations fully contained within a range
+      # @param start_line [Integer] Start line
+      # @param end_line [Integer] End line
+      # @return [Array<Object>] Contained declarations
+      def find_contained_nodes(start_line, end_line)
+        @declarations.select do |decl|
+          decl.location.start_line >= start_line && decl.location.end_line <= end_line
+        end
+      end
+
+      # Find declarations that overlap with a range
+      # @param start_line [Integer] Start line
+      # @param end_line [Integer] End line
+      # @return [Array<Object>] Overlapping declarations
+      def find_overlapping_nodes(start_line, end_line)
+        @declarations.select do |decl|
+          decl_start = decl.location.start_line
+          decl_end = decl.location.end_line
+
+          # Overlaps if not fully before and not fully after
+          !(decl_end < start_line || decl_start > end_line)
+        end
+      end
+
+      # Integrate declarations with freeze blocks, avoiding duplicates
+      # @param declarations [Array] Original declarations
+      # @param freeze_blocks [Array<FreezeNode>] Freeze blocks
+      # @return [Array] Integrated list sorted by line number
+      def integrate_nodes_with_freeze_blocks(declarations, freeze_blocks)
+        # Track which declarations are inside freeze blocks
+        frozen_declarations = freeze_blocks.flat_map(&:nodes).to_set
+
+        # Filter out frozen declarations and add freeze blocks
+        result = declarations.reject { |d| frozen_declarations.include?(d) }
+        result.concat(freeze_blocks)
+
+        # Sort by start line
+        result.sort_by do |node|
+          if node.is_a?(FreezeNode)
+            node.start_line
+          elsif node.respond_to?(:comment) && node.comment
+            # Include comment line in sorting if present
+            [node.comment.location.start_line, node.location.start_line].min
+          else
+            node.location.start_line
+          end
+        end
+      end
+    end
+  end
+end