prism-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/prism/merge/conflict_resolver.rb

@@ -0,0 +1,463 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Prism
+  module Merge
+    # Resolves conflicts in boundaries between anchors using structural
+    # signatures and comment preservation strategies.
+    #
+    # ConflictResolver is responsible for the core merge logic within boundaries
+    # (sections where template and destination differ). It:
+    # - Matches nodes by structural signature
+    # - Decides which version to keep based on preference
+    # - Preserves trailing blank lines for proper spacing
+    # - Handles template-only and destination-only nodes
+    #
+    # @example Basic usage (via SmartMerger)
+    #   resolver = ConflictResolver.new(template_analysis, dest_analysis)
+    #   resolver.resolve(boundary, result)
+    #
+    # @see SmartMerger
+    # @see FileAnalysis
+    # @see MergeResult
+    class ConflictResolver
+      # @return [FileAnalysis] Analysis of the template file
+      attr_reader :template_analysis
+
+      # @return [FileAnalysis] Analysis of the destination file
+      attr_reader :dest_analysis
+
+      # @return [Symbol] Preference for signature matches (:template or :destination)
+      attr_reader :signature_match_preference
+
+      # @return [Boolean] Whether to add template-only nodes
+      attr_reader :add_template_only_nodes
+
+      # Creates a new ConflictResolver for handling merge conflicts.
+      #
+      # @param template_analysis [FileAnalysis] Analyzed template file
+      # @param dest_analysis [FileAnalysis] Analyzed destination file
+      #
+      # @param signature_match_preference [Symbol] Which version to prefer when
+      #   nodes have matching signatures but different content:
+      #   - `:destination` (default) - Keep destination version (customizations)
+      #   - `:template` - Use template version (updates)
+      #
+      # @param add_template_only_nodes [Boolean] Whether to add nodes that only
+      #   exist in template:
+      #   - `false` (default) - Skip template-only nodes
+      #   - `true` - Add template-only nodes to result
+      #
+      # @example Create resolver for Appraisals (destination wins)
+      #   resolver = ConflictResolver.new(
+      #     template_analysis,
+      #     dest_analysis,
+      #     signature_match_preference: :destination,
+      #     add_template_only_nodes: false
+      #   )
+      #
+      # @example Create resolver for version files (template wins)
+      #   resolver = ConflictResolver.new(
+      #     template_analysis,
+      #     dest_analysis,
+      #     signature_match_preference: :template,
+      #     add_template_only_nodes: true
+      #   )
+      def initialize(template_analysis, dest_analysis, signature_match_preference: :destination, add_template_only_nodes: false)
+        @template_analysis = template_analysis
+        @dest_analysis = dest_analysis
+        @signature_match_preference = signature_match_preference
+        @add_template_only_nodes = add_template_only_nodes
+      end
+
+      # Resolve a boundary by deciding which content to keep
+      # @param boundary [FileAligner::Boundary] Boundary to resolve
+      # @param result [MergeResult] Result object to populate
+      def resolve(boundary, result)
+        # Extract content from both sides
+        template_content = extract_boundary_content(@template_analysis, boundary.template_range)
+        dest_content = extract_boundary_content(@dest_analysis, boundary.dest_range)
+
+        # If destination is in freeze block, always keep destination
+        if boundary.dest_range && dest_content[:has_freeze_block]
+          add_content_to_result(dest_content, result, :destination, MergeResult::DECISION_FREEZE_BLOCK)
+          return
+        end
+
+        # If both sides are empty, nothing to do
+        return if template_content[:lines].empty? && dest_content[:lines].empty?
+
+        # If one side is empty, use the other
+        if template_content[:lines].empty?
+          add_content_to_result(dest_content, result, :destination, MergeResult::DECISION_KEPT_DEST)
+          return
+        end
+
+        if dest_content[:lines].empty?
+          add_content_to_result(template_content, result, :template, MergeResult::DECISION_KEPT_TEMPLATE)
+          return
+        end
+
+        # Both sides have content - perform intelligent merge
+        merge_boundary_content(template_content, dest_content, boundary, result)
+      end
+
+      private
+
+      def extract_boundary_content(analysis, line_range)
+        return {lines: [], nodes: [], has_freeze_block: false, line_range: nil} unless line_range
+
+        lines = []
+        line_range.each do |line_num|
+          lines << analysis.line_at(line_num)
+        end
+
+        # Find nodes that intersect with this range
+        nodes = analysis.nodes_with_comments.select do |node_info|
+          node_range = node_info[:line_range]
+          ranges_overlap?(node_range, line_range)
+        end
+
+        # Check for freeze blocks
+        has_freeze_block = line_range.any? { |line_num| analysis.in_freeze_block?(line_num) }
+
+        {
+          lines: lines.map(&:chomp),
+          nodes: nodes,
+          has_freeze_block: has_freeze_block,
+          line_range: line_range,
+        }
+      end
+
+      def ranges_overlap?(range1, range2)
+        range1.begin <= range2.end && range2.begin <= range1.end
+      end
+
+      def add_content_to_result(content, result, source, decision)
+        return if content[:lines].empty?
+
+        start_line = content[:line_range].begin
+        result.add_lines_from(
+          content[:lines],
+          decision: decision,
+          source: source,
+          start_line: start_line,
+        )
+      end
+
+      def merge_boundary_content(template_content, dest_content, _boundary, result)
+        # Strategy: Process template content in order, replacing matched nodes with template version
+        # and appending dest-only nodes at the end
+
+        template_nodes = template_content[:nodes]
+        dest_nodes = dest_content[:nodes]
+
+        # Build signature map for destination nodes
+        dest_sig_map = build_signature_map(dest_nodes)
+
+        # Track which dest nodes have been matched
+        matched_dest_indices = Set.new
+
+        # Build a set of line numbers that are covered by leading comments of nodes
+        # so we don't duplicate them when processing non-node lines
+        leading_comment_lines = Set.new
+        template_nodes.each do |node_info|
+          node_info[:leading_comments].each do |comment|
+            leading_comment_lines << comment.location.start_line
+          end
+        end
+
+        # Process template line by line, adding nodes and non-node lines in order
+        template_line_range = template_content[:line_range]
+        return unless template_line_range
+
+        current_line = template_line_range.begin
+        # Track if we're in a sequence of template-only nodes
+        in_template_only_sequence = false
+        last_added_line = nil
+
+        sorted_nodes = template_nodes.sort_by { |n| n[:line_range].begin }
+
+        sorted_nodes.each_with_index do |t_node_info, idx|
+          node_start = t_node_info[:line_range].begin
+          node_end = t_node_info[:line_range].end
+
+          # Check if this node will be matched or is template-only
+          sig = t_node_info[:signature]
+          is_matched = dest_sig_map[sig]&.any?
+
+          # Calculate the range that includes trailing blank lines up to the next node
+          # This way, blank lines "belong" to the preceding node
+          next_node_start = (idx + 1 < sorted_nodes.length) ? sorted_nodes[idx + 1][:line_range].begin : template_line_range.end + 1
+
+          # Find trailing blank lines after this node
+          trailing_blank_end = node_end
+          (node_end + 1...next_node_start).each do |line_num|
+            break if !template_line_range.cover?(line_num)
+            line = @template_analysis.line_at(line_num)
+            break if !line.strip.empty? # Stop at first non-blank line
+            trailing_blank_end = line_num
+          end
+
+          node_start..trailing_blank_end
+
+          # Add any non-node, non-blank lines before this node (e.g., comments not attached to nodes)
+          if in_template_only_sequence && !is_matched
+            # Skip lines before template-only nodes in a sequence
+            current_line = node_start
+          else
+            while current_line < node_start
+              if template_line_range.cover?(current_line) && !leading_comment_lines.include?(current_line)
+                line = @template_analysis.line_at(current_line)
+                # Only add non-blank lines here (blank lines belong to preceding node)
+                unless line.strip.empty?
+                  add_line_safe(result, line.chomp, decision: MergeResult::DECISION_KEPT_TEMPLATE, template_line: current_line)
+                end
+              end
+              current_line += 1
+            end
+          end
+
+          # Add the node (use configured preference when signatures match)
+          # Include trailing blank lines with the node
+          if is_matched
+            # Match found - use preference to decide which version
+            if @signature_match_preference == :template
+              # Use template version (it's the canonical/updated version)
+              result.add_node(
+                t_node_info,
+                decision: MergeResult::DECISION_REPLACED,
+                source: :template,
+                source_analysis: @template_analysis,
+              )
+            else
+              # Use destination version (it has the customizations)
+              dest_matches = dest_sig_map[sig]
+              result.add_node(
+                dest_matches.first,
+                decision: MergeResult::DECISION_REPLACED,
+                source: :destination,
+                source_analysis: @dest_analysis,
+              )
+            end
+
+            # Mark matching dest nodes as processed
+            dest_matches = dest_sig_map[sig]
+            dest_matches.each do |d_node_info|
+              matched_dest_indices << d_node_info[:index]
+            end
+
+            # Calculate trailing blank lines from destination to preserve original spacing
+            # Use the first matching dest node to determine blank line spacing
+            d_node_info = dest_matches.first
+            d_node = d_node_info[:node]
+            d_node_end = d_node.location.end_line
+            # Find how many blank lines follow this node in destination
+            d_trailing_blank_end = d_node_end
+            if d_node_info[:index] < dest_nodes.size - 1
+              next_dest_info = dest_nodes[d_node_info[:index] + 1]
+              # Find where next node's content actually starts (first leading comment or node itself)
+              next_content_start = if next_dest_info[:leading_comments].any?
+                next_dest_info[:leading_comments].first.location.start_line
+              else
+                next_dest_info[:node].location.start_line
+              end
+
+              # Find all blank lines between this node end and next node's content
+              (d_node_end + 1...next_content_start).each do |line_num|
+                line_content = @dest_analysis.line_at(line_num)
+                if line_content.strip.empty?
+                  d_trailing_blank_end = line_num
+                else
+                  # Stop at first non-blank line
+                  break
+                end
+              end
+            end
+
+            # Add trailing blank lines from destination (preserving destination spacing)
+            (d_node_end + 1..d_trailing_blank_end).each do |line_num|
+              line = @dest_analysis.line_at(line_num)
+              add_line_safe(result, line.chomp, decision: MergeResult::DECISION_KEPT_DEST, dest_line: line_num)
+            end
+
+            in_template_only_sequence = false
+            last_added_line = trailing_blank_end
+          elsif @add_template_only_nodes
+            # No match - this is a template-only node
+            result.add_node(
+              t_node_info,
+              decision: MergeResult::DECISION_KEPT_TEMPLATE,
+              source: :template,
+              source_analysis: @template_analysis,
+            )
+
+            # Add trailing blank lines from template
+            (node_end + 1..trailing_blank_end).each do |line_num|
+              line = @template_analysis.line_at(line_num)
+              add_line_safe(result, line.chomp, decision: MergeResult::DECISION_KEPT_TEMPLATE, template_line: line_num)
+            end
+
+            in_template_only_sequence = false
+            last_added_line = trailing_blank_end
+          # Add the template-only node
+          else
+            # Skip template-only nodes (don't add template nodes that don't exist in destination)
+            in_template_only_sequence = true
+          end
+
+          current_line = trailing_blank_end + 1
+        end
+
+        # Add any remaining template lines after the last node
+        # But skip if we ended in a template-only sequence
+        unless in_template_only_sequence
+          while current_line <= template_line_range.end
+            if !leading_comment_lines.include?(current_line)
+              line = @template_analysis.line_at(current_line)
+              add_line_safe(result, line.chomp, decision: MergeResult::DECISION_KEPT_TEMPLATE, template_line: current_line)
+            end
+            current_line += 1
+          end
+        end
+
+        # Add dest-only nodes (nodes that weren't matched)
+        dest_only_nodes = dest_nodes.select { |d| !matched_dest_indices.include?(d[:index]) }
+
+        unless dest_only_nodes.empty?
+          # Add a blank line before appending dest-only nodes if the result doesn't already end with one
+          if result.lines.any? && !result.lines.last.strip.empty?
+            add_line_safe(result, "", decision: MergeResult::DECISION_KEPT_TEMPLATE)
+          end
+
+          dest_only_nodes.each_with_index do |d_node_info, idx|
+            result.add_node(
+              d_node_info,
+              decision: MergeResult::DECISION_APPENDED,
+              source: :destination,
+              source_analysis: @dest_analysis,
+            )
+
+            # Add trailing blank lines for each dest-only node
+            d_node = d_node_info[:node]
+            d_node_end = d_node.location.end_line
+            d_trailing_blank_end = d_node_end
+
+            # Find trailing blank lines up to the next node or end of boundary
+            if idx < dest_only_nodes.size - 1
+              # Not the last dest-only node - look for next dest-only node
+              next_dest_info = dest_only_nodes[idx + 1]
+              # Find where next node's content actually starts (first leading comment or node itself)
+              next_content_start = if next_dest_info[:leading_comments].any?
+                next_dest_info[:leading_comments].first.location.start_line
+              else
+                next_dest_info[:node].location.start_line
+              end
+
+              # Collect blank lines between this node end and next node's content
+              (d_node_end + 1...next_content_start).each do |line_num|
+                line_content = @dest_analysis.line_at(line_num)
+                if line_content.strip.empty?
+                  d_trailing_blank_end = line_num
+                else
+                  break
+                end
+              end
+            else
+              # This is the last dest-only node - look for trailing blanks up to boundary end
+              # Check lines after this node for blank lines
+              boundary_end = dest_content[:line_range].end
+              line_num = d_node_end + 1
+              while line_num <= boundary_end
+                line_content = @dest_analysis.line_at(line_num)
+                if line_content.strip.empty?
+                  d_trailing_blank_end = line_num
+                  line_num += 1
+                else
+                  break
+                end
+              end
+            end
+
+            # Add trailing blank lines from destination
+            (d_node_end + 1..d_trailing_blank_end).each do |line_num|
+              line = @dest_analysis.line_at(line_num)
+              add_line_safe(result, line.chomp, decision: MergeResult::DECISION_KEPT_DEST, dest_line: line_num)
+            end
+          end
+        end
+      end
+
+      def build_signature_map(nodes)
+        map = Hash.new { |h, k| h[k] = [] }
+        nodes.each do |node_info|
+          sig = node_info[:signature]
+          map[sig] << node_info if sig
+        end
+        map
+      end
+
+      # Add a line to result but avoid adding multiple consecutive blank lines.
+      def add_line_safe(result, content, **kwargs)
+        if content.strip.empty?
+          # If last line is also blank, skip adding to collapse runs of blank lines
+          return if result.lines.any? && result.lines.last.strip.empty?
+        end
+
+        result.add_line(content, **kwargs)
+      end
+
+      def handle_orphan_lines(template_content, dest_content, result)
+        # Find lines that aren't part of any node (pure comments, blank lines)
+        template_orphans = find_orphan_lines(@template_analysis, template_content[:line_range], template_content[:nodes])
+        dest_orphans = find_orphan_lines(@dest_analysis, dest_content[:line_range], dest_content[:nodes])
+
+        # For simplicity, prefer template orphans but add unique dest orphans
+        # This could be enhanced with more sophisticated comment merging
+        template_orphan_content = Set.new(template_orphans.map { |ln| @template_analysis.normalized_line(ln) })
+
+        dest_orphans.each do |line_num|
+          content = @dest_analysis.normalized_line(line_num)
+          next if template_orphan_content.include?(content)
+
+          # Add unique destination orphan
+          line = @dest_analysis.line_at(line_num)
+          result.add_line(
+            line.chomp,
+            decision: MergeResult::DECISION_APPENDED,
+            dest_line: line_num,
+          )
+        end
+      end
+
+      def find_orphan_lines(analysis, line_range, nodes)
+        return [] unless line_range
+
+        # Get all lines covered by nodes
+        covered_lines = Set.new
+        nodes.each do |node_info|
+          node_range = node_info[:line_range]
+          node_range.each { |ln| covered_lines << ln }
+
+          # Also cover comment lines
+          node_info[:leading_comments].each do |comment|
+            covered_lines << comment.location.start_line
+          end
+        end
+
+        # Find uncovered lines
+        orphans = []
+        line_range.each do |line_num|
+          next if covered_lines.include?(line_num)
+
+          # Check if this line has content (not just blank)
+          line = analysis.line_at(line_num)
+          orphans << line_num if line && !line.strip.empty?
+        end
+
+        orphans
+      end
+    end
+  end
+end