kettle-dev 1.1.60 → 1.2.0

data/lib/kettle/dev/modular_gemfiles.rb

@@ -22,25 +22,31 @@ module Kettle
       def sync!(helpers:, project_root:, gem_checkout_root:, min_ruby: nil)
         # 4a) gemfiles/modular/*.gemfile except style.gemfile (handled below)
         # Note: `injected.gemfile` is only intended for testing this gem, and isn't even actively used there. It is not part of the template.
+        # Note: `style.gemfile` is handled separately below.
         modular_gemfiles = %w[
           coverage
           debug
           documentation
           optional
           runtime_heads
+          templating
           x_std_libs
         ]
         modular_gemfiles.each do |base|
           modular_gemfile = "#{base}.gemfile"
           src = helpers.prefer_example(File.join(gem_checkout_root, MODULAR_GEMFILE_DIR, modular_gemfile))
           dest = File.join(project_root, MODULAR_GEMFILE_DIR, modular_gemfile)
-          helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true)
+          existing = File.exist?(dest) ? File.read(dest) : nil
+          helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
+            existing ? helpers.merge_gemfile_dependencies(content, existing) : content
+          end
         end
 
         # 4b) gemfiles/modular/style.gemfile with dynamic rubocop constraints
         modular_gemfile = "style.gemfile"
         src = helpers.prefer_example(File.join(gem_checkout_root, MODULAR_GEMFILE_DIR, modular_gemfile))
         dest = File.join(project_root, MODULAR_GEMFILE_DIR, modular_gemfile)
+        existing_style = File.exist?(dest) ? File.read(dest) : nil
         if File.basename(src).sub(/\.example\z/, "") == "style.gemfile"
           helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
             # Adjust rubocop-lts constraint based on min_ruby
@@ -92,10 +98,12 @@ module Kettle
               token = "{RUBOCOP|RUBY|GEM}"
               content.gsub!(token, "rubocop-ruby#{rubocop_ruby_gem_version}") if content.include?(token)
             end
-            content
+            existing_style ? helpers.merge_gemfile_dependencies(content, existing_style) : content
           end
         else
-          helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true)
+          helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
+            existing_style ? helpers.merge_gemfile_dependencies(content, existing_style) : content
+          end
         end
 
         # 4c) Copy modular directories with nested/versioned files

data/lib/kettle/dev/prism_utils.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Kettle
+  module Dev
+    # Shared utilities for working with Prism AST nodes.
+    # Provides parsing, node inspection, and source generation helpers
+    # used by both PrismMerger and AppraisalsAstMerger.
+    #
+    # Uses Prism's native methods for source generation (via .slice) to preserve
+    # original formatting and comments. For normalized output (e.g., adding parentheses),
+    # use normalize_call_node instead.
+    module PrismUtils
+      module_function
+
+      # Parse Ruby source code and return Prism parse result with comments
+      # @param source [String] Ruby source code
+      # @return [Prism::ParseResult] Parse result containing AST and comments
+      def parse_with_comments(source)
+        Prism.parse(source)
+      end
+
+      # Extract statements from a Prism body node
+      # @param body_node [Prism::Node, nil] Body node (typically StatementsNode)
+      # @return [Array<Prism::Node>] Array of statement nodes
+      def extract_statements(body_node)
+        return [] unless body_node
+
+        if body_node.is_a?(Prism::StatementsNode)
+          body_node.body.compact
+        else
+          [body_node].compact
+        end
+      end
+
+      # Generate a unique key for a statement node to identify equivalent statements
+      # Used for merge/append operations to detect duplicates
+      # @param node [Prism::Node] Statement node
+      # @param tracked_methods [Array<Symbol>] Methods to track (default: gem, source, eval_gemfile, git_source)
+      # @return [Array, nil] Key array like [:gem, "foo"] or nil if not trackable
+      def statement_key(node, tracked_methods: %i[gem source eval_gemfile git_source])
+        return unless node.is_a?(Prism::CallNode)
+        return unless tracked_methods.include?(node.name)
+
+        first_arg = node.arguments&.arguments&.first
+        arg_value = extract_literal_value(first_arg)
+
+        [node.name, arg_value] if arg_value
+      end
+
+      # Extract literal value from string or symbol nodes
+      # @param node [Prism::Node, nil] Node to extract from
+      # @return [String, Symbol, nil] Literal value or nil
+      def extract_literal_value(node)
+        case node
+        when Prism::StringNode then node.unescaped
+        when Prism::SymbolNode then node.unescaped
+        end
+      end
+
+      # Extract qualified constant name from a constant node
+      # @param node [Prism::Node, nil] Constant node
+      # @return [String, nil] Qualified name like "Gem::Specification" or nil
+      def extract_const_name(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          parent = extract_const_name(node.parent)
+          child = node.name || node.child&.name
+          (parent && child) ? "#{parent}::#{child}" : child.to_s
+        end
+      end
+
+      # Find leading comments for a statement node
+      # Leading comments are those that appear after the previous statement
+      # and before the current statement
+      # @param parse_result [Prism::ParseResult] Parse result with comments
+      # @param current_stmt [Prism::Node] Current statement node
+      # @param prev_stmt [Prism::Node, nil] Previous statement node
+      # @param body_node [Prism::Node] Body containing the statements
+      # @return [Array<Prism::Comment>] Leading comments
+      def find_leading_comments(parse_result, current_stmt, prev_stmt, body_node)
+        start_line = prev_stmt ? prev_stmt.location.end_line : body_node.location.start_line
+        end_line = current_stmt.location.start_line
+
+        parse_result.comments.select do |comment|
+          comment.location.start_line > start_line &&
+            comment.location.start_line < end_line
+        end
+      end
+
+      # Find inline comments for a statement node
+      # Inline comments are those that appear on the same line as the statement's end
+      # @param parse_result [Prism::ParseResult] Parse result with comments
+      # @param stmt [Prism::Node] Statement node
+      # @return [Array<Prism::Comment>] Inline comments
+      def inline_comments_for_node(parse_result, stmt)
+        parse_result.comments.select do |comment|
+          comment.location.start_line == stmt.location.end_line &&
+            comment.location.start_offset > stmt.location.end_offset
+        end
+      end
+
+      # Convert a Prism AST node to Ruby source code
+      # Uses Prism's native slice method which preserves the original source exactly.
+      # This is preferable to Unparser for Prism nodes as it maintains original formatting
+      # and comments without requiring transformation.
+      # @param node [Prism::Node] AST node
+      # @return [String] Ruby source code
+      def node_to_source(node)
+        return "" unless node
+        # Prism nodes have a slice method that returns the original source
+        node.slice
+      end
+
+      # Normalize a call node to use parentheses format
+      # Converts `gem "foo"` to `gem("foo")` style
+      # @param node [Prism::CallNode] Call node
+      # @return [String] Normalized source code
+      def normalize_call_node(node)
+        return node.slice.strip unless node.is_a?(Prism::CallNode)
+
+        method_name = node.name
+        args = node.arguments&.arguments || []
+
+        if args.empty?
+          "#{method_name}()"
+        else
+          arg_strings = args.map { |arg| normalize_argument(arg) }
+          "#{method_name}(#{arg_strings.join(", ")})"
+        end
+      end
+
+      # Normalize an argument node to canonical format
+      # @param arg [Prism::Node] Argument node
+      # @return [String] Normalized argument source
+      def normalize_argument(arg)
+        case arg
+        when Prism::StringNode
+          "\"#{arg.unescaped}\""
+        when Prism::SymbolNode
+          ":#{arg.unescaped}"
+        when Prism::KeywordHashNode
+          # Handle hash arguments like {key: value}
+          pairs = arg.elements.map do |assoc|
+            key = case assoc.key
+            when Prism::SymbolNode then "#{assoc.key.unescaped}:"
+            when Prism::StringNode then "\"#{assoc.key.unescaped}\" =>"
+            else "#{assoc.key.slice} =>"
+            end
+            value = normalize_argument(assoc.value)
+            "#{key} #{value}"
+          end.join(", ")
+          pairs
+        when Prism::HashNode
+          # Handle explicit hash syntax
+          pairs = arg.elements.map do |assoc|
+            key_part = normalize_argument(assoc.key)
+            value_part = normalize_argument(assoc.value)
+            "#{key_part} => #{value_part}"
+          end.join(", ")
+          "{#{pairs}}"
+        else
+          # For other types (numbers, arrays, etc.), use the original source
+          arg.slice.strip
+        end
+      end
+
+      # Check if a node is a specific method call
+      # @param node [Prism::Node] Node to check
+      # @param method_name [Symbol] Method name to check for
+      # @return [Boolean] True if node is a call to the specified method
+      def call_to?(node, method_name)
+        node.is_a?(Prism::CallNode) && node.name == method_name
+      end
+
+      # Check if a node is a block call to a specific method
+      # @param node [Prism::Node] Node to check
+      # @param method_name [Symbol] Method name to check for
+      # @return [Boolean] True if node is a block call to the specified method
+      def block_call_to?(node, method_name)
+        node.is_a?(Prism::CallNode) && node.name == method_name && !node.block.nil?
+      end
+    end
+  end
+end

data/lib/kettle/dev/source_merger.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "set"
+require "prism"
+require "kettle/dev/prism_utils"
+
+module Kettle
+  module Dev
+    # Prism-based AST merging for templated Ruby files.
+    # Handles universal freeze reminders, kettle-dev:freeze blocks, and
+    # strategy dispatch (skip/replace/append/merge).
+    #
+    # Uses Prism for parsing with first-class comment support, enabling
+    # preservation of inline and leading comments throughout the merge process.
+    module SourceMerger
+      FREEZE_START = /#\s*kettle-dev:freeze/i
+      FREEZE_END = /#\s*kettle-dev:unfreeze/i
+      FREEZE_BLOCK = Regexp.new("(#{FREEZE_START.source}).*?(#{FREEZE_END.source})", Regexp::IGNORECASE | Regexp::MULTILINE)
+      FREEZE_REMINDER = <<~RUBY
+        # To retain during kettle-dev templating:
+        #     kettle-dev:freeze
+        #     # ... your code
+        #     kettle-dev:unfreeze
+      RUBY
+      BUG_URL = "https://github.com/kettle-rb/kettle-dev/issues"
+
+      module_function
+
+      # Apply a templating strategy to merge source and destination Ruby files
+      #
+      # @param strategy [Symbol] Merge strategy - :skip, :replace, :append, or :merge
+      # @param src [String] Template source content
+      # @param dest [String] Destination file content
+      # @param path [String] File path (for error messages)
+      # @return [String] Merged content with freeze blocks and comments preserved
+      # @raise [Kettle::Dev::Error] If strategy is unknown or merge fails
+      # @example
+      #   SourceMerger.apply(
+      #     strategy: :merge,
+      #     src: 'gem "foo"',
+      #     dest: 'gem "bar"',
+      #     path: "Gemfile"
+      #   )
+      def apply(strategy:, src:, dest:, path:)
+        strategy = normalize_strategy(strategy)
+        dest ||= ""
+        src_with_reminder = ensure_reminder(src)
+        content =
+          case strategy
+          when :skip
+            src_with_reminder
+          when :replace
+            normalize_source(src_with_reminder)
+          when :append
+            apply_append(src_with_reminder, dest)
+          when :merge
+            apply_merge(src_with_reminder, dest)
+          else
+            raise Kettle::Dev::Error, "Unknown templating strategy '#{strategy}' for #{path}."
+          end
+        content = merge_freeze_blocks(content, dest)
+        content = restore_custom_leading_comments(dest, content)
+        ensure_trailing_newline(content)
+      rescue StandardError => error
+        warn_bug(path, error)
+        raise Kettle::Dev::Error, "Template merge failed for #{path}: #{error.message}"
+      end
+
+      # Ensure freeze reminder comment is present at the top of content
+      #
+      # @param content [String] Ruby source content
+      # @return [String] Content with freeze reminder prepended if missing
+      # @api private
+      def ensure_reminder(content)
+        return content if reminder_present?(content)
+        insertion_index = reminder_insertion_index(content)
+        before = content[0...insertion_index]
+        after = content[insertion_index..-1]
+        snippet = FREEZE_REMINDER
+        snippet += "\n" unless snippet.end_with?("\n\n")
+        [before, snippet, after].join
+      end
+
+      # Normalize source code while preserving formatting
+      #
+      # @param source [String] Ruby source code
+      # @return [String] Normalized source with trailing newline
+      # @api private
+      def normalize_source(source)
+        parse_result = PrismUtils.parse_with_comments(source)
+        return ensure_trailing_newline(source) unless parse_result.success?
+
+        # Use Prism's slice to preserve original formatting
+        ensure_trailing_newline(source)
+      end
+
+      def reminder_present?(content)
+        content.include?(FREEZE_REMINDER.lines.first.strip)
+      end
+
+      def reminder_insertion_index(content)
+        cursor = 0
+        lines = content.lines
+        lines.each do |line|
+          break unless shebang?(line) || frozen_comment?(line)
+          cursor += line.length
+        end
+        cursor
+      end
+
+      def shebang?(line)
+        line.start_with?("#!")
+      end
+
+      def frozen_comment?(line)
+        line.match?(/#\s*frozen_string_literal:/)
+      end
+
+      # Merge kettle-dev:freeze blocks from destination into source content
+      # Preserves user customizations wrapped in freeze/unfreeze markers
+      #
+      # @param src_content [String] Template source content
+      # @param dest_content [String] Destination file content
+      # @return [String] Merged content with freeze blocks from destination
+      # @api private
+      def merge_freeze_blocks(src_content, dest_content)
+        dest_blocks = freeze_blocks(dest_content)
+        return src_content if dest_blocks.empty?
+        src_blocks = freeze_blocks(src_content)
+        updated = src_content.dup
+        # Replace matching freeze sections by textual markers rather than index ranges
+        dest_blocks.each do |dest_block|
+          marker = dest_block[:text]
+          next if updated.include?(marker)
+          # If the template had a placeholder block, replace the first occurrence of a freeze stub
+          placeholder = src_blocks.find { |blk| blk[:start_marker] == dest_block[:start_marker] }
+          if placeholder
+            updated.sub!(placeholder[:text], marker)
+          else
+            updated << "\n" unless updated.end_with?("\n")
+            updated << marker
+          end
+        end
+        updated
+      end
+
+      def freeze_blocks(text)
+        return [] unless text&.match?(FREEZE_START)
+        blocks = []
+        text.to_enum(:scan, FREEZE_BLOCK).each do
+          match = Regexp.last_match
+          start_idx = match&.begin(0)
+          end_idx = match&.end(0)
+          next unless start_idx && end_idx
+          segment = match[0]
+          start_marker = segment.lines.first&.strip
+          blocks << {range: start_idx...end_idx, text: segment, start_marker: start_marker}
+        end
+        blocks
+      end
+
+      def normalize_strategy(strategy)
+        return :skip if strategy.nil?
+        strategy.to_s.downcase.strip.to_sym
+      end
+
+      def warn_bug(path, error)
+        puts "ERROR: kettle-dev templating failed for #{path}: #{error.message}"
+        puts "Please file a bug at #{BUG_URL} with the file contents so we can improve the AST merger."
+      end
+
+      def ensure_trailing_newline(text)
+        return "" if text.nil?
+        text.end_with?("\n") ? text : text + "\n"
+      end
+
+      def apply_append(src_content, dest_content)
+        prism_merge(src_content, dest_content) do |src_nodes, dest_nodes, _src_result, _dest_result|
+          existing = Set.new(dest_nodes.map { |node| node_signature(node[:node]) })
+          appended = dest_nodes.dup
+          src_nodes.each do |node_info|
+            sig = node_signature(node_info[:node])
+            next if existing.include?(sig)
+            appended << node_info
+            existing << sig
+          end
+          appended
+        end
+      end
+
+      def apply_merge(src_content, dest_content)
+        prism_merge(src_content, dest_content) do |src_nodes, dest_nodes, _src_result, _dest_result|
+          src_map = src_nodes.each_with_object({}) do |node_info, memo|
+            sig = node_signature(node_info[:node])
+            memo[sig] ||= node_info
+          end
+          merged = dest_nodes.map do |node_info|
+            sig = node_signature(node_info[:node])
+            if (src_node_info = src_map[sig])
+              merge_node_info(sig, node_info, src_node_info)
+            else
+              node_info
+            end
+          end
+          existing = merged.map { |ni| node_signature(ni[:node]) }.to_set
+          src_nodes.each do |node_info|
+            sig = node_signature(node_info[:node])
+            next if existing.include?(sig)
+            merged << node_info
+            existing << sig
+          end
+          merged
+        end
+      end
+
+      def merge_node_info(signature, _dest_node_info, src_node_info)
+        return src_node_info unless signature.is_a?(Array)
+        case signature[1]
+        when :gem_specification
+          merge_block_node_info(src_node_info)
+        else
+          src_node_info
+        end
+      end
+
+      def merge_block_node_info(src_node_info)
+        # For block merging, we need to merge the statements within the block
+        # This is complex - for now, prefer template version
+        # TODO: Implement deep block statement merging with comment preservation
+        src_node_info
+      end
+
+      def prism_merge(src_content, dest_content)
+        src_result = PrismUtils.parse_with_comments(src_content)
+        dest_result = PrismUtils.parse_with_comments(dest_content)
+
+        src_nodes = extract_nodes_with_comments(src_result)
+        dest_nodes = extract_nodes_with_comments(dest_result)
+
+        merged_nodes = yield(src_nodes, dest_nodes, src_result, dest_result)
+
+        build_source_from_nodes(merged_nodes)
+      end
+
+      def extract_nodes_with_comments(parse_result)
+        return [] unless parse_result.success?
+
+        statements = PrismUtils.extract_statements(parse_result.value.statements)
+        return [] if statements.empty?
+
+        statements.map.with_index do |stmt, idx|
+          prev_stmt = (idx > 0) ? statements[idx - 1] : nil
+          body_node = parse_result.value.statements
+
+          {
+            node: stmt,
+            leading_comments: PrismUtils.find_leading_comments(parse_result, stmt, prev_stmt, body_node),
+            inline_comments: PrismUtils.inline_comments_for_node(parse_result, stmt),
+          }
+        end
+      end
+
+      def build_source_from_nodes(node_infos)
+        return "" if node_infos.empty?
+
+        lines = []
+        node_infos.each do |node_info|
+          # Add leading comments
+          node_info[:leading_comments].each do |comment|
+            lines << comment.slice.rstrip
+          end
+
+          # Add the node's source
+          node_source = PrismUtils.node_to_source(node_info[:node])
+
+          # Add inline comments on the same line
+          if node_info[:inline_comments].any?
+            inline = node_info[:inline_comments].map { |c| c.slice.strip }.join(" ")
+            node_source = node_source.rstrip + " " + inline
+          end
+
+          lines << node_source
+        end
+
+        lines.join("\n")
+      end
+
+      def node_signature(node)
+        return [:nil] unless node
+
+        case node
+        when Prism::CallNode
+          method_name = node.name
+          if node.block
+            # Block call
+            first_arg = PrismUtils.extract_literal_value(node.arguments&.arguments&.first)
+            receiver_name = PrismUtils.extract_const_name(node.receiver)
+
+            if receiver_name == "Gem::Specification" && method_name == :new
+              [:block, :gem_specification]
+            elsif method_name == :task
+              [:block, :task, first_arg]
+            elsif method_name == :git_source
+              [:block, :git_source, first_arg]
+            else
+              [:block, method_name, first_arg, node.slice]
+            end
+          elsif [:source, :git_source, :gem, :eval_gemfile].include?(method_name)
+            # Simple call
+            first_literal = PrismUtils.extract_literal_value(node.arguments&.arguments&.first)
+            [:send, method_name, first_literal]
+          else
+            [:send, method_name, node.slice]
+          end
+        else
+          # Other node types
+          [node.class.name.split("::").last.to_sym, node.slice]
+        end
+      end
+
+      def restore_custom_leading_comments(dest_content, merged_content)
+        block = leading_comment_block(dest_content)
+        return merged_content if block.strip.empty?
+        return merged_content if merged_content.start_with?(block)
+
+        # Insert after shebang / frozen string literal comments (same place reminder goes)
+        insertion_index = reminder_insertion_index(merged_content)
+        block = ensure_trailing_newline(block)
+        merged_content.dup.insert(insertion_index, block)
+      end
+
+      def leading_comment_block(content)
+        lines = content.to_s.lines
+        collected = []
+        lines.each do |line|
+          stripped = line.strip
+          break unless stripped.empty? || stripped.start_with?("#")
+          collected << line
+        end
+        collected.join
+      end
+    end
+  end
+end

data/lib/kettle/dev/tasks/template_task.rb

@@ -252,7 +252,8 @@ module Kettle
 
               # If a destination gemspec already exists, get metadata from GemSpecReader via helpers
               orig_meta = nil
-              if File.exist?(dest_gemspec)
+              dest_existed = File.exist?(dest_gemspec)
+              if dest_existed
                 begin
                   orig_meta = helpers.gemspec_metadata(File.dirname(dest_gemspec))
                 rescue StandardError => e
@@ -387,6 +388,15 @@ module Kettle
                   # If anything goes wrong, keep the content as-is rather than failing the task
                 end
 
+                if dest_existed
+                  begin
+                    merged = helpers.apply_strategy(c, dest_gemspec)
+                    c = merged if merged.is_a?(String) && !merged.empty?
+                  rescue StandardError => e
+                    Kettle::Dev.debug_error(e, __method__)
+                  end
+                end
+
                 c
               end
             end