prism-merge 7.1.8 → 7.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9bb0cd6d347f5231bdc73d9fdf4f752dc4900a8a4fda3d1a93e8749673e1d94
-  data.tar.gz: 1d0763e1c290d0026f1bf2a6d44b4657b3353c8cb6813597e0943eaa8a4b2369
+  metadata.gz: 0311a16d60cb4d5bb9ad04d1223c05e85aa80056a4d14f00087f6d0fed6c2909
+  data.tar.gz: f65258b654893b9be95415ebfe05c0f634b3a92273c81d0169ee29b1584ef068
 SHA512:
-  metadata.gz: 23a30711093805e44d7faa6888f24db54d51f741ab033e6d1f8353375df03941ef65007bcb0ce0f1af1137ce86ac4bfebedd3f15aa47035acb1964c4f5333488
-  data.tar.gz: 958a34605f7d99be74c799f77072e95b8490184b04e7318c16efc3f00983cb1c16ac1dcb5585e05927548bc39e44c81fb9a01403fd2338428ea26b7d6d783bd4
+  metadata.gz: 2c2f70118664e21623d068196cf057afe65f535f54442f1b03957a9a5a126a0809ad24235a6c39b94945267d1f2220788bd37696098ba7e2b12856202a7433ff
+  data.tar.gz: 32592677ef4e368db093730cc25064c532e4d02e10bf3f149a39ca46c5bcf47386b315fc1c3f396c7f87820883820c575607c4d23062b1d75f12618e97b2fec4

data/lib/prism/merge/comment/block.rb

@@ -49,6 +49,21 @@ module Prism
         #
         # For non-magic blocks, uses the parent implementation.
         #
+        # == NOT PART OF PRAGMA RESOLUTION
+        #
+        # This signature makes a comment-only file's magic comment matchable as a
+        # top-level node. That is the mechanism by which a file-level pragma can be
+        # treated as ordinary content and emitted at the wrong position: when the
+        # destination is comment-only, its pragma becomes a node whose signature
+        # cannot match the template's pragma (which is a leading comment of the
+        # template's first statement, not a statement), so it lands after the last
+        # template statement where Ruby ignores it.
+        #
+        # Do NOT extend pragma handling here. Which pragmas survive a merge, and
+        # where they are placed, is decided by {Prism::Merge::PragmaMerger}, wired
+        # in from {Prism::Merge::SmartMerger#apply_pragma_header} after this
+        # resolver runs. This signature governs comment-block MATCHING only.
+        #
         # @return [Array] Signature for matching
         def signature
           if contains_magic_comment?

data/lib/prism/merge/comment/line.rb

@@ -58,6 +58,20 @@ module Prism
         # - `# warn_indent: true/false`
         # - `# shareable_constant_value: literal/...`
         #
+        # == CLASSIFICATION ONLY, NOT PRAGMA RESOLUTION
+        #
+        # This attribute feeds comment classification and node signatures. It does
+        # not decide whether a pragma survives a merge or where it is placed - that
+        # is {Prism::Merge::PragmaMerger}, wired in from
+        # {Prism::Merge::SmartMerger#apply_pragma_header}. PragmaMerger reads
+        # Prism's native ParseResult#magic_comments directly and does not consult
+        # this attribute.
+        #
+        # Do not build pragma retention or placement on top of this. Note also that
+        # `magic_comment_type` is populated only for comments in the header prefix,
+        # so it is not a reliable test for "is this text a pragma" elsewhere in a
+        # file.
+        #
         # @return [Boolean] true if this is a magic comment
         def magic_comment?
           !@magic_comment_type.nil?

data/lib/prism/merge/comment/parser.rb

@@ -33,6 +33,10 @@ module Prism
 
           nodes = []
           current_block = []
+          # CLASSIFICATION ONLY: tags comment lines so Comment::Line can carry a
+          # magic_comment_type for node signatures. Not pragma resolution - see
+          # Prism::Merge::PragmaMerger, applied by
+          # Prism::Merge::SmartMerger#apply_pragma_header after the merge.
           header_magic_comment_types = Prism::Merge::MagicCommentSupport.header_magic_comment_types_for_lines(lines)
 
           lines.each_with_index do |line, idx|

data/lib/prism/merge/comment_only_file_merger.rb

@@ -2,6 +2,28 @@
 
 module Prism
   module Merge
+    # Merges files whose top-level statements are ALL comments (no code).
+    #
+    # Dispatched from TopLevelMergeRunner#comment_only_merge?, which requires BOTH
+    # sides to be comment-only. A mixed pair - e.g. a comment-only destination
+    # merged into a template that has code - takes the main node path instead.
+    #
+    # == NOT THE PRAGMA RESOLVER
+    #
+    # The header handling here (comment_only_prefix_info, duplicate_magic_line_nums,
+    # emit_comment_only_prefix_lines) deduplicates magic comments WITHIN one side's
+    # own header prefix. It does not resolve pragmas ACROSS template and
+    # destination, and it does not run at all for a mixed pair.
+    #
+    # That gap is why a comment-only destination's pragma used to be emitted as an
+    # unmatched node at the end of the merged file, where Ruby ignores it. Which
+    # pragmas survive a merge and where they are placed is decided by
+    # {Prism::Merge::PragmaMerger}, wired in from
+    # {Prism::Merge::SmartMerger#apply_pragma_header} after the resolver runs, so it
+    # covers both dispatch paths uniformly.
+    #
+    # Keep this class focused on comment-only files. Do not extend it to resolve
+    # pragma retention or placement.
     class CommentOnlyFileMerger
       attr_reader :merger, :comment_only_prefix_lines
 

data/lib/prism/merge/file_analysis.rb

@@ -809,6 +809,17 @@ module Prism
         }
       end
 
+      # Magic comment types in this file's header prefix, keyed by line number.
+      #
+      # CLASSIFICATION ONLY. Used to populate Comment::Line#magic_comment_type so
+      # comment nodes can be typed and signed. Not pragma resolution: it does not
+      # decide which pragmas survive a merge or where they are placed. See
+      # Prism::Merge::PragmaMerger (wired in via
+      # Prism::Merge::SmartMerger#apply_pragma_header) for that.
+      #
+      # Note this is regex/line-based (via MagicCommentSupport) and only covers the
+      # contiguous header prefix - it breaks at the first blank line. PragmaMerger
+      # instead reads Prism's native ParseResult#magic_comments.
       def native_header_magic_comment_types
         @native_header_magic_comment_types ||= Prism::Merge::MagicCommentSupport.header_magic_comment_types_for_lines(@lines)
       end

data/lib/prism/merge/magic_comment_support.rb

@@ -3,6 +3,49 @@
 module Prism
   module Merge
     # Compatibility wrapper for Ruby substrate magic-comment support.
+    #
+    # == THIS IS NOT THE PRAGMA RESOLVER
+    #
+    # Do not add new magic-comment / pragma handling here, or in any of the
+    # callers listed below. This module only classifies comment TEXT and reports
+    # header line numbers. It does not decide which pragmas survive a merge, nor
+    # where they are placed.
+    #
+    # The authoritative resolver for file-level pragmas is
+    # {Prism::Merge::PragmaMerger}, wired in from
+    # {Prism::Merge::SmartMerger#apply_pragma_header}. Pragma semantics live there:
+    #
+    #   KEPT     - preference resolved exactly like ordinary content, honouring
+    #              add_template_only_nodes and remove_template_missing_nodes
+    #   POSITION - always pinned to the header region (below any shebang), because
+    #              Ruby ignores a magic comment that appears after the first
+    #              statement
+    #
+    # Anything built on this module instead will silently reintroduce the two
+    # defects PragmaMerger exists to prevent: a pragma stranded below code (inert,
+    # Lint/MisplacedMagicComment) and a pragma dropped because retention followed
+    # `preference` alone rather than the add/remove flags.
+    #
+    # == Remaining consumers (legacy, classification only)
+    #
+    # These still consult this module. Each is a COMMENT CLASSIFICATION or node
+    # SIGNATURE concern, not pragma retention or placement, and none may grow
+    # pragma handling:
+    #
+    #   lib/prism/merge/comment/line.rb              magic_comment_type attribute
+    #   lib/prism/merge/comment/block.rb             contains_magic_comment?, magic_comments
+    #   lib/prism/merge/comment/parser.rb            header classification while parsing
+    #   lib/prism/merge/file_analysis.rb             native_header_magic_comment_types
+    #   lib/prism/merge/comment_only_file_merger.rb  comment-only file header handling
+    #   lib/prism/merge/node_emission_support.rb     leading-comment prefix emission
+    #   lib/prism/merge/recursive_node_body_merger.rb prefix comment filtering
+    #   lib/prism/merge/wrapper_comment_support.rb   leading-comment emission
+    #   lib/prism/merge/ruby_doc_surface_analyzer.rb doc-comment vs directive split
+    #   lib/prism/merge.rb                           prism_comment_directive classification
+    #
+    # Removing them is deliberately deferred: Comment::Line#magic_comment_type
+    # feeds node signatures, so deleting it changes match identity well beyond
+    # pragmas. That work needs its own pass with the full monorepo suite as guard.
     module MagicCommentSupport
       module_function
 

data/lib/prism/merge/node_emission_support.rb

@@ -2,6 +2,24 @@
 
 module Prism
   module Merge
+    # Emits nodes and their comments into the MergeResult.
+    #
+    # == PRAGMAS ARE NOT PLACED HERE
+    #
+    # The prefix/leading-comment emission below positions ordinary comments. A
+    # file-level pragma (magic comment) is NOT placed by this class, and must not
+    # be: Ruby honours a pragma only when it precedes the first statement, so its
+    # position cannot depend on which node happens to carry it.
+    #
+    # Pragma retention and placement are resolved by {Prism::Merge::PragmaMerger},
+    # applied once by {Prism::Merge::SmartMerger#apply_pragma_header} after the
+    # whole merge finishes. That post-pass strips pragmas from wherever emission
+    # put them and pins the resolved block to the header region, so it is correct
+    # regardless of the path taken here.
+    #
+    # Consequence: a pragma may transiently appear at the wrong position in the
+    # result this class builds. That is expected and repaired downstream. Do not
+    # add pragma-specific handling here to pre-empt it.
     class NodeEmissionSupport
       include Prism::Merge::SourceLineLookup
 

data/lib/prism/merge/pragma_merger.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+module Prism
+  module Merge
+    # Merges file-level pragmas as a discrete document.
+    #
+    # == Why a dedicated resolver
+    #
+    # A magic comment is syntactically a comment but semantically a file-level
+    # directive, and the two axes of a merge resolve differently for it:
+    #
+    #   KEPT     - preference resolved, exactly like any other content. Either
+    #              side may add or remove a pragma, governed by the same
+    #              `preference`, `add_template_only_nodes` and
+    #              `remove_template_missing_nodes` settings that govern code.
+    #   POSITION - never follows merge placement rules. Ruby only honours a magic
+    #              comment that appears in the leading comment region, before the
+    #              first statement; one emitted after code is inert. So a pragma
+    #              must always be pinned to the top.
+    #
+    # Modelling a pragma as an ordinary comment attached to a statement satisfies
+    # neither axis: it inherits the host statement's placement (so it can be
+    # stranded below code, silently disabling e.g. frozen string literals), and it
+    # bypasses the add/remove flags (which operate on statements), so retention
+    # follows `preference` alone.
+    #
+    # Treating the pragma region as its own document resolves both at once:
+    # retention is computed here by the same rule code uses, and the rendered block
+    # is pinned above the first statement, so it cannot be misplaced.
+    #
+    # == Scope
+    #
+    # Only file-level pragmas are handled here. Prism classifies ANY leading
+    # `# key: value` as a magic comment, which includes block directives such as
+    # `# kettle-jem:freeze` and `# simplecov:disable`. Those are positionally
+    # meaningful and legitimately appear mid-file, so they are excluded by key and
+    # remain the main resolver's concern.
+    #
+    # Identity and position come from Prism natively (ParseResult#magic_comments
+    # with key, value and value_loc), so no text pattern matching is involved.
+    #
+    # == What this REPLACES
+    #
+    # Magic-comment handling elsewhere in this gem is legacy and is classification
+    # only. It must not grow pragma retention or placement logic. Each such site
+    # carries a "NOT THE PRAGMA RESOLVER" / "CLASSIFICATION ONLY" marker pointing
+    # back here:
+    #
+    #   magic_comment_support.rb       regex/line-based header classification
+    #   comment/line.rb                magic_comment_type attribute (feeds signatures)
+    #   comment/block.rb               signature making a pragma matchable as a node
+    #   comment/parser.rb              header tagging during parse
+    #   file_analysis.rb               native_header_magic_comment_types
+    #   comment_only_file_merger.rb    within-one-side header dedup only
+    #   node_emission_support.rb       leading-comment prefix emission
+    #   wrapper_comment_support.rb     leading-comment emission
+    #   recursive_node_body_merger.rb  prefix comment filtering
+    #   ruby_doc_surface_analyzer.rb   doc-vs-directive split
+    #   merge.rb                       prism_comment_directive classification
+    #
+    # Removing them is deliberately deferred: Comment::Line#magic_comment_type feeds
+    # node signatures, so deleting it changes match identity well beyond pragmas.
+    # That needs its own pass with the full monorepo suite as guard.
+    #
+    # @example
+    #   merger = PragmaMerger.new(
+    #     template_source: template,
+    #     destination_source: destination,
+    #     preference: :destination,
+    #     add_template_only_nodes: true,
+    #     remove_template_missing_nodes: false
+    #   )
+    #   merger.resolved_entries  # => [#<Entry key="frozen_string_literal" value="true" line=1>]
+    #   merger.render            # => "# frozen_string_literal: true\n"
+    #   merger.place_in(body)    # => pragma block pinned above the first statement
+    #
+    # @example Removing pragmas the node resolver emitted
+    #   PragmaMerger.strip_pragma_lines("# frozen_string_literal: true\nx = 1\n")
+    #   # => "x = 1\n"
+    # rubocop:disable Metrics/ClassLength -- the retention rule, the rendering of the
+    # pragma block, its header placement, and the AST-derived line scan form one
+    # boundary: splitting them across classes would separate the two merge axes
+    # (KEPT and POSITION) that must stay resolved together.
+    class PragmaMerger
+      # File-level pragmas, as opposed to block directives. Filtering happens on
+      # the AST-derived key (Set membership), never by matching comment text.
+      PRAGMA_KEYS = %w[
+        frozen_string_literal
+        encoding
+        coding
+        warn_indent
+        shareable_constant_value
+      ].to_set.freeze
+
+      # A single pragma occurrence.
+      #
+      # @!attribute key
+      #   @return [String] pragma name, e.g. "frozen_string_literal"
+      # @!attribute value
+      #   @return [String] pragma value, e.g. "true"
+      # @!attribute line
+      #   @return [Integer] 1-based source line the pragma occupies
+      Entry = Struct.new(:key, :value, :line, keyword_init: true) do
+        # Renders the pragma in canonical `# key: value` form.
+        #
+        # @return [String]
+        def to_line
+          "# #{key}: #{value}"
+        end
+      end
+
+      # @param template_source [String]
+      # @param destination_source [String]
+      # @param preference [Symbol] :destination or :template
+      # @param add_template_only_nodes [Boolean]
+      # @param remove_template_missing_nodes [Boolean]
+      def initialize(template_source:, destination_source:, preference: :destination,
+                     add_template_only_nodes: false, remove_template_missing_nodes: false)
+        @template_source = template_source.to_s
+        @destination_source = destination_source.to_s
+        @preference = preference.to_sym
+        @add_template_only_nodes = add_template_only_nodes
+        @remove_template_missing_nodes = remove_template_missing_nodes
+      end
+
+      attr_reader :preference
+
+      # Pragma entries declared by the template, in source order.
+      #
+      # @return [Array<Entry>]
+      def template_entries
+        @template_entries ||= entries_for(@template_source)
+      end
+
+      # Pragma entries declared by the destination, in source order.
+      #
+      # @return [Array<Entry>]
+      def destination_entries
+        @destination_entries ||= entries_for(@destination_source)
+      end
+
+      # The pragmas to keep, in render order.
+      #
+      # Retention mirrors how ordinary nodes resolve:
+      #   declared by both      -> kept, value resolved by preference
+      #   template only         -> kept iff preference is :template, or
+      #                            add_template_only_nodes is set
+      #   destination only      -> kept iff remove_template_missing_nodes is unset
+      #
+      # Order is deterministic: template order first, then any destination-only
+      # pragma in destination order. The template is the authority on header
+      # structure; ordering is not itself preference resolved because neither side
+      # expresses an ordering preference for a region it may not declare at all.
+      #
+      # @return [Array<Entry>]
+      def resolved_entries
+        @resolved_entries ||= compute_resolved_entries
+      end
+
+      # True when at least one pragma survives the merge.
+      #
+      # @return [Boolean]
+      def any?
+        resolved_entries.any?
+      end
+
+      # Renders the merged pragma block, one pragma per line, no trailing newline
+      # separation logic (callers place it in the header region).
+      #
+      # @return [String] empty when no pragma is kept
+      def render
+        return '' if resolved_entries.empty?
+
+        resolved_entries.map { |entry| "#{entry.to_line}\n" }.join
+      end
+
+      # Places the merged pragma block into +content+, honouring the two
+      # positional constraints Ruby imposes:
+      #
+      #   * a shebang must remain the very first line, so pragmas go below it
+      #   * pragmas must precede the first statement, so they go above all code
+      #
+      # A blank line separates the block from whatever follows, matching normal
+      # file layout. Returns +content+ unchanged when no pragma is kept.
+      #
+      # @param content [String] merged body with pragma lines already removed
+      # @return [String]
+      def place_in(content)
+        block = render
+        return content.to_s if block.empty?
+
+        text = content.to_s
+        lines = text.lines
+        shebang = lines.first.to_s.start_with?('#!') ? lines.shift : nil
+        prefix = [shebang, block].compact
+        rest = drop_leading_blank_lines(lines)
+        [*prefix, "\n", *rest].join
+      end
+
+      # Removes pragma lines from +source+, leaving every other line untouched.
+      #
+      # A line is only removed when the pragma is the whole line. A pragma sharing
+      # a line with code is left alone rather than risk corrupting the statement,
+      # which cannot happen for a recognised magic comment in any case.
+      #
+      # @param source [String]
+      # @return [String]
+      def self.strip_pragma_lines(source)
+        text = source.to_s
+        return text if text.empty?
+
+        lines_to_drop = pragma_line_numbers(text)
+        return text if lines_to_drop.empty?
+
+        text.lines.each_with_index.reject { |_, index| lines_to_drop.include?(index + 1) }.map(&:first).join
+      end
+
+      # Line numbers (1-based) occupied by a file-level pragma in +source+.
+      #
+      # @param source [String]
+      # @return [Set<Integer>]
+      def self.pragma_line_numbers(source)
+        parse = Prism.parse(source.to_s)
+        lines = source.to_s.lines
+        pragma_magic_comments(parse)
+          .filter_map { |magic_comment| pragma_line(magic_comment, lines) }
+          .to_set
+      end
+
+      # Prism's own magic comments, narrowed to the file-level pragma keys.
+      def self.pragma_magic_comments(parse)
+        parse.magic_comments.select { |magic_comment| PRAGMA_KEYS.include?(magic_comment.key.to_s) }
+      end
+
+      # The 1-based line a pragma occupies, or nil when the pragma shares its line
+      # with code. Only wholly-comment lines are reported, so stripping one cannot
+      # take code with it.
+      def self.pragma_line(magic_comment, lines)
+        line = magic_comment.value_loc.start_line
+        comment_only_line?(lines[line - 1]) ? line : nil
+      end
+
+      def self.comment_only_line?(line)
+        line.to_s.strip.start_with?('#')
+      end
+
+      private
+
+      def compute_resolved_entries
+        by_key = merge_entry_values
+        apply_template_retention(by_key)
+        order_entries(by_key)
+      end
+
+      # Indexes every pragma by key, resolving the value where both sides declare
+      # one. A destination-only pragma is recorded exactly when destination-only
+      # nodes would be kept.
+      def merge_entry_values
+        by_key = {}
+        template_entries.each { |entry| by_key[entry.key] ||= entry }
+        destination_entries.each do |entry|
+          merged = merged_entry(by_key[entry.key], entry)
+          by_key[entry.key] = merged unless merged.nil?
+        end
+        by_key
+      end
+
+      # Resolves one key present on the template side (+existing+) against the
+      # destination side (+entry+). Returns nil when the pragma should not be
+      # recorded at all.
+      def merged_entry(existing, entry)
+        return merged_conflicting_entry(existing, entry) if existing
+
+        keep_destination_only? ? entry : nil
+      end
+
+      # Both sides declare the pragma, so it is always kept and only its value is
+      # preference resolved. The template's line anchors the rendered position.
+      def merged_conflicting_entry(existing, entry)
+        Entry.new(key: entry.key, value: preferred_value(existing.value, entry.value), line: existing.line)
+      end
+
+      # Drops template-declared pragmas whose retention rule says they do not
+      # survive, mirroring how template-only nodes are dropped.
+      def apply_template_retention(by_key)
+        template_entries.each do |entry|
+          by_key.delete(entry.key) unless keep_template_declared?(entry.key)
+        end
+        by_key
+      end
+
+      # Template order first, then destination-only pragmas in destination order.
+      def order_entries(by_key)
+        template_keys = template_entries.map(&:key).uniq
+        ordered = template_keys.filter_map { |key| by_key[key] }
+        destination_only = destination_entries.map(&:key).uniq - template_keys
+        ordered + destination_only.filter_map { |key| by_key[key] }
+      end
+
+      def keep_template_declared?(key)
+        template_declares = template_entries.any? { |entry| entry.key == key }
+        destination_declares = destination_entries.any? { |entry| entry.key == key }
+        # Declared by both: retention is unconditional, only the value is resolved.
+        return true if template_declares && destination_declares
+        return false unless template_declares
+
+        # Template-only: retained exactly when template-only NODES are retained.
+        # `preference` does not govern this. Measured against ordinary code, a
+        # template-only method or constant is dropped under preference: :template
+        # when add_template_only_nodes is false, and kept under
+        # preference: :destination when it is true - so presence of a one-sided
+        # node follows the add/remove flags, while preference only resolves
+        # conflicts between nodes both sides declare. Treating preference as an
+        # addition trigger would make pragmas resolve differently from code.
+        @add_template_only_nodes
+      end
+
+      def keep_destination_only?
+        !@remove_template_missing_nodes
+      end
+
+      def preferred_value(template_value, destination_value)
+        preference == :template ? template_value : destination_value
+      end
+
+      # Drops leading blank lines so the pragma block is followed by exactly one
+      # separator blank line rather than accumulating them across repeated merges
+      # (idempotency).
+      def drop_leading_blank_lines(lines)
+        index = 0
+        index += 1 while index < lines.length && lines[index].to_s.strip.empty?
+        lines[index..] || []
+      end
+
+      def entries_for(source)
+        return [] if source.empty?
+
+        parse = Prism.parse(source)
+        parse.magic_comments.filter_map do |magic_comment|
+          key = magic_comment.key.to_s
+          next unless PRAGMA_KEYS.include?(key)
+
+          Entry.new(key: key, value: magic_comment.value.to_s, line: magic_comment.value_loc.start_line)
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/prism/merge/recursive_node_body_merger.rb

@@ -62,6 +62,10 @@ module Prism
         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_prefix_comment_lines = merger.instance_variable_get(:@dest_prefix_comment_lines)
+        # CLASSIFICATION ONLY: filters header comments already claimed as prefix
+        # lines so they are not re-emitted inside a recursive body merge. This is
+        # comment dedup, not pragma resolution - see Prism::Merge::PragmaMerger,
+        # applied by Prism::Merge::SmartMerger#apply_pragma_header.
         template_prefix_line_numbers = Prism::Merge::MagicCommentSupport.prefix_comment_line_numbers_for_comments(template_comments)
         dest_claimed = merger.dest_analysis.respond_to?(:claimed_lines) ? merger.dest_analysis.claimed_lines : Set.new
         template_claimed = merger.template_analysis.respond_to?(:claimed_lines) ? merger.template_analysis.claimed_lines : Set.new

data/lib/prism/merge/ruby_doc_surface_analyzer.rb

@@ -163,6 +163,12 @@ module Prism
         Ruby::Merge::BlockDirectiveDetector.directive_content?(content)
       end
 
+      # CLASSIFICATION ONLY: decides whether a header comment is documentation or
+      # a directive/pragma, so the doc surface excludes non-prose comments. This is
+      # a documentation concern, not pragma resolution - it does not decide which
+      # pragmas survive a merge or where they are placed. See
+      # Prism::Merge::PragmaMerger, applied by
+      # Prism::Merge::SmartMerger#apply_pragma_header.
       def magic_comment_line?(entry, content)
         node = entry[:node]
         return true if node.respond_to?(:magic_comment_type) && !node.magic_comment_type.nil?

data/lib/prism/merge/smart_merger.rb

@@ -274,11 +274,57 @@ module Prism
       # @return [MergeResult] The merge result
       def perform_merge
         validate_files!
-        top_level_merge_runner.merge
+        apply_pragma_header(top_level_merge_runner.merge)
       end
 
       private
 
+      # Resolves file-level pragmas as a discrete document and pins the result to
+      # the top of the merged output.
+      #
+      # The main resolver treats a magic comment as an ordinary comment attached to
+      # a statement, which satisfies neither axis of pragma semantics: it inherits
+      # the host statement's placement, so it can be stranded below code where Ruby
+      # ignores it; and it bypasses the add/remove flags that govern statements, so
+      # retention follows `preference` alone. PragmaMerger resolves both.
+      #
+      # Applied after the merge rather than by stripping the inputs, so line numbers
+      # recorded in MergeResult#line_metadata keep matching the source files they
+      # came from. This mirrors how regions rewrite content post-hoc via
+      # update_result_content.
+      #
+      # @param result [MergeResult]
+      # @return [MergeResult]
+      def apply_pragma_header(result)
+        return result if result.nil?
+
+        merged_content = result.to_s
+        merger = build_pragma_merger
+        # Strips pragmas the main resolver emitted anywhere in the file, then pins
+        # the preference-resolved block above the first statement (and below any
+        # shebang). A no-op when neither side declares a pragma.
+        pinned = merger.place_in(PragmaMerger.strip_pragma_lines(merged_content))
+        return result if pinned == merged_content
+
+        # MergeResult#to_s appends a trailing newline, while the inherited
+        # content= splits with -1 and so keeps a trailing empty line. Passing the
+        # pinned text through unchanged would therefore add a blank line at the end
+        # of the file on every merge. Removing exactly one trailing newline makes
+        # the assignment round-trip.
+        update_result_content(result, pinned.sub(/\n\z/, ''))
+        result
+      end
+
+      def build_pragma_merger
+        PragmaMerger.new(
+          template_source: template_content,
+          destination_source: dest_content,
+          preference: preference,
+          add_template_only_nodes: add_template_only_nodes,
+          remove_template_missing_nodes: remove_template_missing_nodes
+        )
+      end
+
       def record_runtime_session(session)
         @runtime_session = session
       end

data/lib/prism/merge/version.rb

@@ -5,7 +5,7 @@ module Prism
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = '7.1.8'
+      VERSION = '7.1.10'
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/prism/merge/wrapper_comment_support.rb

@@ -2,6 +2,18 @@
 
 module Prism
   module Merge
+    # Selects and emits the leading/trailing comments attached to a node.
+    #
+    # == PRAGMAS ARE NOT PLACED HERE
+    #
+    # prefix_comment_line_numbers_for_comments is consulted to avoid re-emitting
+    # header comments already claimed as prefix lines. That is comment dedup within
+    # one side's header, NOT pragma resolution: it does not decide which pragmas
+    # survive a merge, nor where they are placed.
+    #
+    # File-level pragmas are resolved by {Prism::Merge::PragmaMerger} and pinned by
+    # {Prism::Merge::SmartMerger#apply_pragma_header} after the merge completes.
+    # Do not add pragma retention or placement logic to this class.
     class WrapperCommentSupport
       include Prism::Merge::SourceLineLookup
 

data/lib/prism/merge.rb

@@ -58,6 +58,7 @@ module Prism
     autoload :MethodMatchRefiner, 'prism/merge/method_match_refiner'
     autoload :NestedStatementWalker, 'prism/merge/nested_statement_walker'
     autoload :NocovNode, 'prism/merge/nocov_node'
+    autoload :PragmaMerger, 'prism/merge/pragma_merger'
     autoload :NoCovWrapper, 'prism/merge/nocov_wrapper'
     autoload :NodeBodyLayout, 'prism/merge/node_body_layout'
     autoload :NodeEmissionSupport, 'prism/merge/node_emission_support'
@@ -1235,6 +1236,17 @@ module Prism
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
+    # Classifies a comment for node-signature and doc-surface purposes.
+    #
+    # == CLASSIFICATION ONLY, NOT PRAGMA RESOLUTION
+    #
+    # The 'magic_comment' kind here labels a comment so it can be matched and
+    # documented. It does not decide whether a pragma survives a merge or where it
+    # is placed - that is Prism::Merge::PragmaMerger, wired in from
+    # Prism::Merge::SmartMerger#apply_pragma_header, which reads Prism's native
+    # ParseResult#magic_comments directly and does not consult this method.
+    #
+    # Do not build pragma retention or placement on this classification.
     def prism_comment_directive(comment_text, magic_comment)
       if comment_text.strip.match?(/\A#\s*smorg:freeze\b/)
         {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prism-merge
 version: !ruby/object:Gem::Version
-  version: 7.1.8
+  version: 7.1.10
 platform: ruby
 authors:
 - Peter H. Boling
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.8
+        version: 7.1.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.8
+        version: 7.1.10
 - !ruby/object:Gem::Dependency
   name: prism
   requirement: !ruby/object:Gem::Requirement
@@ -71,28 +71,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.8
+        version: 7.1.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.8
+        version: 7.1.10
 - !ruby/object:Gem::Dependency
   name: tree_haver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.8
+        version: 7.1.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.8
+        version: 7.1.10
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -119,20 +119,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.31
+        version: 3.1.8
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.31
+        version: 3.1.8
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -210,7 +210,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 3.2.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -220,7 +220,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -230,7 +230,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.21
+        version: 2.0.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -240,7 +240,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.21
+        version: 2.0.23
 - !ruby/object:Gem::Dependency
   name: turbo_tests2
   requirement: !ruby/object:Gem::Requirement
@@ -250,7 +250,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.7
+        version: 3.2.14
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -260,7 +260,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.7
+        version: 3.2.14
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -284,7 +284,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -294,7 +294,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.9
 - !ruby/object:Gem::Dependency
   name: gitmoji-regex
   requirement: !ruby/object:Gem::Requirement
@@ -304,7 +304,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.12
+        version: 2.0.15
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -314,7 +314,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.12
+        version: 2.0.15
 description: "☯️ Prism-backed Ruby provider gem for the Structured Merge Ruby family."
 email:
 - floss@galtzo.com
@@ -358,6 +358,7 @@ files:
 - lib/prism/merge/node_wrapper.rb
 - lib/prism/merge/partial_template_merger.rb
 - lib/prism/merge/partial_template_node.rb
+- lib/prism/merge/pragma_merger.rb
 - lib/prism/merge/provider.rb
 - lib/prism/merge/recursive_merge_policy.rb
 - lib/prism/merge/recursive_node_body_merger.rb
@@ -376,10 +377,10 @@ licenses:
 - PolyForm-Small-Business-1.0.0
 metadata:
   homepage_uri: https://structuredmerge.org
-  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.8
-  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.8/CHANGELOG.md
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.10
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.10/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/prism-merge/7.1.8
+  documentation_uri: https://www.rubydoc.info/gems/prism-merge/7.1.10
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/prism-merge
@@ -409,7 +410,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: "☯️ Structured Merge Prism-backed Ruby analysis for Ruby"
 test_files: []