prism-merge 2.0.3 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '058627bf3c8cc38b58815faddda8774645a25a06f8dd00116fac3c5368cad1f4'
-  data.tar.gz: 75eb6d7b4db6fe1774e45964bada3c2b3396d4d4efb8b5c8813d4f52b07ce120
+  metadata.gz: 025344bcf44324e19df2d0519fc8f935a0c51c1236d2299407ca52ec406e6a13
+  data.tar.gz: a3f1a6fe2a2ede10fa8c5072268bd384a850d9cbd8e2e95a206e39158e426ec4
 SHA512:
-  metadata.gz: 84b86d2c1052489cb9deef903966a1f2c5bdb3523efa93e88e5cd3cc7df5bc52838910b328790e6106e6904ae0df9356d3c54b28aa8e724a95f8210ff014d228
-  data.tar.gz: f67161e7e0500d7f1c819a0ba9ec6e459fb46cd3da8a05dfe386c245f0fcfaf56912cb22675d3c4547cd0cc98a66aae26023939f7453c13df16202acd0000a3b
+  metadata.gz: e2e182168a6014be8e7d3c8ad2130886e63938ac2e7543675a323284cd7cae73667d4b0309b3faa4ae778c241c0b22dc58f03a50d37431f71e0ed9381fdbdd31
+  data.tar.gz: 5ec2df827e3bd5f749fdd26576f145f0244f37fa167aa85d101a2fd538fc4b88683c74497bb43e7ae366287b44ca1a39c8afc2ca7fc35bbb219c92c17efe5b20

data/CHANGELOG.md

@@ -30,6 +30,33 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.0.4] - 2026-02-22
+
+- TAG: [v2.0.4][2.0.4t]
+- COVERAGE: 98.34% -- 891/906 lines in 12 files
+- BRANCH COVERAGE: 84.34% -- 501/594 branches in 12 files
+- 93.51% documented
+
+### Fixed
+
+- Always preserve destination magic comments (`# frozen_string_literal: true`,
+  `# encoding: UTF-8`, etc.) at the top of merged output, regardless of merge
+  preference. Magic comments are file-level metadata managed by Prism and must
+  not be lost when the template side lacks them (e.g. after filtering).
+  `emit_dest_prefix_lines` now detects contiguous magic comments from the first
+  destination node's leading comments, emits them before any template-only nodes
+  (Phase 1), and records the emitted line numbers so `add_node_to_result` and
+  `merge_node_body_recursively` skip them to prevent duplication.
+- Non-top-of-file magic comments (e.g. used as documentation) are left alone and
+  treated as regular comments.
+- Fix blank line preservation between magic comments and subsequent comments when
+  template preference is used. Gap lines between a stripped magic comment and the
+  next remaining comment are now correctly emitted from the template source.
+- Fix inter-node gap line preservation when a matched node is output from the
+  template source. `perform_merge` now checks whether the output source's
+  analysis had a trailing blank before advancing `last_output_dest_line`, so
+  `emit_dest_gap_lines` correctly emits dest gap lines that the template lacked.
+
 ## [2.0.3] - 2026-02-22
 
 - TAG: [v2.0.3][2.0.3t]
@@ -354,7 +381,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/prism-merge/compare/v2.0.3...HEAD
+[Unreleased]: https://github.com/kettle-rb/prism-merge/compare/v2.0.4...HEAD
+[2.0.4]: https://github.com/kettle-rb/prism-merge/compare/v2.0.3...v2.0.4
+[2.0.4t]: https://github.com/kettle-rb/prism-merge/releases/tag/v2.0.4
 [2.0.3]: https://github.com/kettle-rb/prism-merge/compare/v2.0.2...v2.0.3
 [2.0.3t]: https://github.com/kettle-rb/prism-merge/releases/tag/v2.0.3
 [2.0.2]: https://github.com/kettle-rb/prism-merge/compare/v2.0.1...v2.0.2

data/README.md

@@ -1564,7 +1564,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.839-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.906-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/prism/merge/smart_merger.rb

@@ -93,6 +93,7 @@ module Prism
         @max_recursion_depth = max_recursion_depth
         @current_depth = current_depth
         @text_merger_options = text_merger_options
+        @dest_prefix_comment_lines = nil
 
         # Store the raw (unwrapped) signature_generator so that
         # merge_node_body_recursively can pass it to inner SmartMergers
@@ -228,6 +229,10 @@ module Prism
         # Track which dest line ranges have been output (to avoid duplicating nested content)
         output_dest_line_ranges = []
 
+        # Emit dest magic comments first — they must always be at the very
+        # top of the output, before any template-only nodes from Phase 1.
+        last_output_dest_line = emit_dest_prefix_lines(@result, @dest_analysis)
+
         # Phase 1: Output template-only nodes first (nodes in template but not in dest)
         # This ensures template-only nodes (like `source` in Gemfiles) appear at the top
         if @add_template_only_nodes
@@ -246,9 +251,6 @@ module Prism
         # Phase 2: Process dest nodes in their original order
         # This preserves dest-only nodes in their original position relative to matched nodes
 
-        # Emit prefix lines from the dest source (magic comments, blank lines before first node)
-        last_output_dest_line = emit_dest_prefix_lines(@result, @dest_analysis)
-
         @dest_analysis.statements.each do |dest_node|
           dest_signature = @dest_analysis.generate_signature(dest_node)
 
@@ -262,6 +264,11 @@ module Prism
           # Emit inter-node gap lines from the dest source (blank lines between blocks)
           last_output_dest_line = emit_dest_gap_lines(@result, @dest_analysis, last_output_dest_line, dest_node)
 
+          # Track which source/analysis was used for output so we can check
+          # whether a trailing blank was emitted from that source's analysis.
+          output_node = dest_node
+          output_analysis = @dest_analysis
+
           if dest_signature && template_by_signature.key?(dest_signature)
             # Matched node - merge with template version
             template_node = template_by_signature[dest_signature]
@@ -273,12 +280,19 @@ module Prism
             if should_merge_recursively?(template_node, dest_node)
               # Recursively merge class/module/block bodies
               merge_node_body_recursively(template_node, dest_node)
+              node_pref = preference_for_node(template_node, dest_node)
+              if node_pref == :template
+                output_node = template_node.respond_to?(:unwrap) ? template_node.unwrap : template_node
+                output_analysis = @template_analysis
+              end
             else
               # Output based on preference
               node_preference = preference_for_node(template_node, dest_node)
 
               if node_preference == :template
                 add_node_to_result(@result, template_node, @template_analysis, :template)
+                output_node = template_node
+                output_analysis = @template_analysis
               else
                 add_node_to_result(@result, dest_node, @dest_analysis, :destination)
               end
@@ -290,11 +304,20 @@ module Prism
             output_signatures << dest_signature if dest_signature
           end
 
-          # Update last_output_dest_line to track trailing blank line from add_node_to_result
+          # Update last_output_dest_line. Advance past the trailing blank
+          # only if the output source actually has a trailing blank (meaning
+          # add_node_to_result / merge_node_body_recursively emitted it).
           last_output_dest_line = dest_node.location.end_line
-          trailing_line = last_output_dest_line + 1
-          trailing_content = @dest_analysis.line_at(trailing_line)
-          last_output_dest_line = trailing_line if trailing_content && trailing_content.strip.empty?
+          actual_output_end = output_node.respond_to?(:unwrap) ? output_node.unwrap.location.end_line : output_node.location.end_line
+          trailing_line_num = actual_output_end + 1
+          trailing_content = output_analysis.line_at(trailing_line_num)
+          if trailing_content && trailing_content.strip.empty?
+            # The output source had a trailing blank that was emitted.
+            # Advance last_output_dest_line so emit_dest_gap_lines doesn't re-emit it.
+            trailing_dest_line = dest_node.location.end_line + 1
+            dest_trailing = @dest_analysis.line_at(trailing_dest_line)
+            last_output_dest_line = trailing_dest_line if dest_trailing && dest_trailing.strip.empty?
+          end
         end
 
         @result
@@ -614,33 +637,105 @@ module Prism
         }
       end
 
-      # Emit prefix lines from the destination source that appear before the first node.
-      # This preserves magic comments (e.g., `# frozen_string_literal: true`) and blank
-      # lines that precede any AST statements.
+      # Emit destination magic comments and any lines that precede the first
+      # AST node's leading comments.
+      #
+      # Magic comments (frozen_string_literal, encoding, etc.) are file-level
+      # metadata managed by Prism. The destination is the real file on disk,
+      # so its magic comments must always be preserved — regardless of merge
+      # preference. This method:
+      #
+      # 1. Emits any lines before the first leading comment (shebangs, etc.)
+      # 2. Emits magic comments from the first dest node's leading comments
+      # 3. Emits blank lines between the last magic comment and the first
+      #    non-magic leading comment (or the node itself)
+      # 4. Records which dest line numbers were emitted so that
+      #    add_node_to_result can skip them (preventing duplication)
       #
       # @param result [MergeResult] The merge result
       # @param analysis [FileAnalysis] The destination file analysis
       # @return [Integer] The last line number emitted (0 if none)
       def emit_dest_prefix_lines(result, analysis)
+        @dest_prefix_comment_lines = Set.new
         return 0 if analysis.statements.empty?
 
         first_node = analysis.statements.first
-        # Find the first line of content: either leading comment or node start
         leading_comments = first_node.location.respond_to?(:leading_comments) ? first_node.location.leading_comments : []
         first_content_line = leading_comments.any? ? leading_comments.first.location.start_line : first_node.location.start_line
 
-        return 0 if first_content_line <= 1
-
-        # Emit lines before the first node (magic comments, blank lines)
         last_emitted = 0
-        (1...first_content_line).each do |line_num|
-          line = analysis.line_at(line_num)&.chomp || ""
+
+        # Step 1: Emit lines before first leading comment (shebangs, etc.)
+        if first_content_line > 1
+          (1...first_content_line).each do |line_num|
+            line = analysis.line_at(line_num)&.chomp || ""
+            result.add_line(line, decision: MergeResult::DECISION_KEPT_DEST, dest_line: line_num)
+            @dest_prefix_comment_lines << line_num
+            last_emitted = line_num
+          end
+        end
+
+        # Step 2: Emit contiguous magic comments from the top of the
+        # leading comments list, plus blank lines between them and the
+        # next non-magic content.
+        magic_end_index = -1
+        leading_comments.each_with_index do |comment, idx|
+          break unless prism_magic_comment?(comment)
+          magic_end_index = idx
+        end
+
+        return last_emitted if magic_end_index < 0
+
+        # Emit magic comment lines
+        (0..magic_end_index).each do |idx|
+          comment = leading_comments[idx]
+          line_num = comment.location.start_line
+          line = analysis.line_at(line_num)&.chomp || comment.slice.rstrip
+
+          # Emit gap lines between consecutive magic comments
+          if last_emitted > 0 && line_num > last_emitted + 1
+            ((last_emitted + 1)...line_num).each do |gap_num|
+              gap = analysis.line_at(gap_num)&.chomp || ""
+              result.add_line(gap, decision: MergeResult::DECISION_KEPT_DEST, dest_line: gap_num)
+              @dest_prefix_comment_lines << gap_num
+            end
+          end
+
           result.add_line(line, decision: MergeResult::DECISION_KEPT_DEST, dest_line: line_num)
+          @dest_prefix_comment_lines << line_num
           last_emitted = line_num
         end
+
+        # Emit blank lines between last magic comment and next content
+        next_content_line = if magic_end_index + 1 < leading_comments.size
+          leading_comments[magic_end_index + 1].location.start_line
+        else
+          first_node.location.start_line
+        end
+
+        if next_content_line > last_emitted + 1
+          ((last_emitted + 1)...next_content_line).each do |gap_num|
+            gap_line = analysis.line_at(gap_num)&.chomp || ""
+            next unless gap_line.strip.empty?
+
+            result.add_line(gap_line, decision: MergeResult::DECISION_KEPT_DEST, dest_line: gap_num)
+            @dest_prefix_comment_lines << gap_num
+            last_emitted = gap_num
+          end
+        end
+
         last_emitted
       end
 
+      # Check if a Prism comment object is a Ruby magic comment.
+      #
+      # @param comment [Prism::Comment] A Prism comment object
+      # @return [Boolean]
+      def prism_magic_comment?(comment)
+        text = comment.slice.sub(/\A#\s*/, "").strip
+        Comment::Line::MAGIC_COMMENT_PATTERNS.any? { |_, pat| text.match?(pat) }
+      end
+
       # Emit blank/gap lines from the destination source between the last output line
       # and the next node (including its leading comments). This preserves blank lines
       # that separate top-level blocks.
@@ -686,18 +781,49 @@ module Prism
           MergeResult::DECISION_KEPT_DEST
         end
 
-        # Get leading comments attached to the node
-        leading_comments = node.location.respond_to?(:leading_comments) ? node.location.leading_comments : []
+        # Get leading comments attached to the node, skipping any that were
+        # already emitted by emit_dest_prefix_lines (dest magic comments at
+        # the top of the file). Non-top-of-file magic comments are left alone
+        # — they may be documentation or intentional repetition.
+        #
+        # For dest nodes: skip by exact line number match.
+        # For template nodes: skip magic comments if dest prefix already
+        # emitted magic comments (to avoid duplication).
+        all_leading_comments = node.location.respond_to?(:leading_comments) ? node.location.leading_comments : []
+        last_skipped_line = nil
+        leading_comments = if source == :destination
+          all_leading_comments.reject do |c|
+            if @dest_prefix_comment_lines&.include?(c.location.start_line)
+              last_skipped_line = c.location.start_line
+              true
+            end
+          end
+        elsif @dest_prefix_comment_lines&.any?
+          all_leading_comments.reject do |c|
+            if prism_magic_comment?(c)
+              last_skipped_line = c.location.start_line
+              true
+            end
+          end
+        else
+          all_leading_comments
+        end
 
         # Add leading comments first (includes freeze markers if present)
-        # Also add any blank lines between consecutive comments
-        prev_comment_line = nil
+        # Also add any blank lines between consecutive comments.
+        # For template nodes where magic comments were skipped, seed
+        # prev_comment_line so gap lines between the stripped comment and
+        # the next remaining comment are properly emitted.
+        prev_comment_line = (source == :template) ? last_skipped_line : nil
         leading_comments.each do |comment|
           line_num = comment.location.start_line
 
           # Add blank lines between this comment and the previous one
           if prev_comment_line && line_num > prev_comment_line + 1
             ((prev_comment_line + 1)...line_num).each do |blank_line_num|
+              # Skip lines already emitted by emit_dest_prefix_lines
+              next if @dest_prefix_comment_lines&.include?(blank_line_num)
+
               line = analysis.line_at(blank_line_num)&.chomp || ""
               if source == :template
                 result.add_line(line, decision: decision, template_line: blank_line_num)
@@ -724,6 +850,9 @@ module Prism
           if node.location.start_line > last_comment_line + 1
             # There's a gap - add blank lines
             ((last_comment_line + 1)...node.location.start_line).each do |line_num|
+              # Skip lines already emitted by emit_dest_prefix_lines
+              next if @dest_prefix_comment_lines&.include?(line_num)
+
               line = analysis.line_at(line_num)&.chomp || ""
               if source == :template
                 result.add_line(line, decision: decision, template_line: line_num)
@@ -906,12 +1035,23 @@ module Prism
         # Get preference for this specific node pair
         node_preference = preference_for_node(template_node, dest_node)
 
-        # Determine which comments to use:
+        # Determine which comments to use (skipping any already emitted
+        # by emit_dest_prefix_lines):
         # - If template preference and template has comments, use template's
         # - If template preference but template has NO comments, preserve dest's comments
         # - If dest preference, use dest's comments
         template_comments = actual_template.location.respond_to?(:leading_comments) ? actual_template.location.leading_comments : []
         dest_comments = actual_dest.location.respond_to?(:leading_comments) ? actual_dest.location.leading_comments : []
+        dest_comments = dest_comments.reject { |c| @dest_prefix_comment_lines&.include?(c.location.start_line) }
+        last_skipped_template_line = nil
+        if @dest_prefix_comment_lines&.any?
+          template_comments = template_comments.reject do |c|
+            if prism_magic_comment?(c)
+              last_skipped_template_line = c.location.start_line
+              true
+            end
+          end
+        end
 
         # Choose comment source: prefer dest comments if template has none (to preserve existing headers)
         if node_preference == :template && template_comments.empty? && dest_comments.any?
@@ -933,14 +1073,19 @@ module Prism
         source_node = (node_preference == :template) ? actual_template : actual_dest
         decision = MergeResult::DECISION_REPLACED
 
-        # Add leading comments with blank lines between them preserved
-        prev_comment_line = nil
+        # Add leading comments with blank lines between them preserved.
+        # Seed prev_comment_line for template source so gap lines between
+        # stripped magic comments and remaining comments are preserved.
+        prev_comment_line = (comment_source == :template) ? last_skipped_template_line : nil
         leading_comments.each do |comment|
           line_num = comment.location.start_line
 
           # Add blank lines between this comment and the previous one
           if prev_comment_line && line_num > prev_comment_line + 1
             ((prev_comment_line + 1)...line_num).each do |blank_line_num|
+              # Skip lines already emitted by emit_dest_prefix_lines
+              next if @dest_prefix_comment_lines&.include?(blank_line_num)
+
               line = comment_analysis.line_at(blank_line_num)&.chomp || ""
               if comment_source == :template
                 @result.add_line(line, decision: decision, template_line: blank_line_num)

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 = "2.0.3"
+      VERSION = "2.0.4"
     end
     VERSION = Version::VERSION # traditional location
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prism-merge
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.0.4
 platform: ruby
 authors:
 - Peter H. Boling
@@ -314,10 +314,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://prism-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/prism-merge/tree/v2.0.3
-  changelog_uri: https://github.com/kettle-rb/prism-merge/blob/v2.0.3/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/prism-merge/tree/v2.0.4
+  changelog_uri: https://github.com/kettle-rb/prism-merge/blob/v2.0.4/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/prism-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/prism-merge/2.0.3
+  documentation_uri: https://www.rubydoc.info/gems/prism-merge/2.0.4
   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