kettle-dev 1.1.59 → 1.2.0

data/Rakefile.example

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kettle-dev Rakefile v1.1.59 - 2025-11-13
+# kettle-dev Rakefile v1.2.0 - 2025-11-25
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/gemfiles/modular/style.gemfile.example

@@ -13,7 +13,7 @@ gem "rubocop-on-rbs", "~> 1.8"                    # ruby >= 3.1.0
 gem "benchmark", "~> 0.4", ">= 0.4.1" # Removed from Std Lib in Ruby 3.5
 
 if ENV.fetch("RUBOCOP_LTS_LOCAL", "false").casecmp("true").zero?
-  home = ENV["HOME"]
+  home = ENV["HOME"] || Dir.home
   gem "rubocop-lts", path: "#{home}/src/rubocop-lts/rubocop-lts"
   gem "rubocop-lts-rspec", path: "#{home}/src/rubocop-lts/rubocop-lts-rspec"
   gem "{RUBOCOP|RUBY|GEM}", path: "#{home}/src/rubocop-lts/{RUBOCOP|RUBY|GEM}"

data/gemfiles/modular/templating.gemfile

@@ -0,0 +1,3 @@
+# Ruby parsing for advanced templating
+gem "prism", "~> 1.6"
+gem "unparser", "~> 0.8", ">= 0.8.1"

data/lib/kettle/dev/appraisals_ast_merger.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+require "prism"
+require "kettle/dev/prism_utils"
+
+module Kettle
+  module Dev
+    # AST-driven merger for Appraisals files using Prism.
+    # Preserves all comments: preamble headers, block headers, and inline comments.
+    # Uses PrismUtils for shared Prism AST operations.
+    module AppraisalsAstMerger
+      TRACKED_METHODS = [:gem, :eval_gemfile, :gemfile].freeze
+
+      module_function
+
+      # Merge template and destination Appraisals files preserving comments
+      #
+      # Merges appraise blocks by name, preserving:
+      # - Preamble comments (deduplicated)
+      # - Block headers (comments before each appraise block)
+      # - Inline comments on gem/eval_gemfile statements
+      # - Leading comments before statements
+      #
+      # @param template_content [String] Template Appraisals content
+      # @param dest_content [String] Destination Appraisals content
+      # @return [String] Merged Appraisals content with preserved comments
+      # @example
+      #   AppraisalsAstMerger.merge(
+      #     'appraise "rails-7" { gem "rails", "~> 7.0" }',
+      #     'appraise "custom" { gem "foo" }'
+      #   )
+      def merge(template_content, dest_content)
+        template_content ||= ""
+        dest_content ||= ""
+
+        return template_content if dest_content.strip.empty?
+        return dest_content if template_content.strip.empty?
+
+        # Parse with Prism to get AST and comments
+        tmpl_result = PrismUtils.parse_with_comments(template_content)
+        dest_result = PrismUtils.parse_with_comments(dest_content)
+
+        # Extract preamble and blocks with their headers
+        tmpl_preamble, tmpl_blocks = extract_blocks(tmpl_result, template_content)
+        dest_preamble, dest_blocks = extract_blocks(dest_result, dest_content)
+
+        # Merge preambles
+        merged_preamble = merge_preambles(tmpl_preamble, dest_preamble)
+
+        # Merge blocks
+        merged_blocks = merge_blocks(tmpl_blocks, dest_blocks, tmpl_result, dest_result)
+
+        # Build output
+        build_output(merged_preamble, merged_blocks)
+      end
+
+      def extract_blocks(parse_result, source_content)
+        root = parse_result.value
+        return [[], []] unless root&.statements&.body
+
+        source_lines = source_content.lines
+        blocks = []
+        first_appraise_line = nil
+
+        # Find all appraise blocks
+        root.statements.body.each do |node|
+          if appraise_call?(node)
+            first_appraise_line ||= node.location.start_line
+            name = extract_appraise_name(node)
+            next unless name
+
+            # Extract block header (comments immediately before this block)
+            block_header = extract_block_header(node, source_lines, blocks)
+
+            blocks << {
+              node: node,
+              name: name,
+              header: block_header,
+            }
+          end
+        end
+
+        # Preamble is all comments before first appraise block
+        preamble_comments = if first_appraise_line
+          parse_result.comments.select { |c| c.location.start_line < first_appraise_line }
+        else
+          parse_result.comments
+        end
+
+        # Filter out comments that are part of block headers
+        block_header_lines = blocks.flat_map { |b| b[:header].lines.map { |l| l.strip } }.to_set
+        preamble_comments = preamble_comments.reject { |c| block_header_lines.include?(c.slice.strip) }
+
+        [preamble_comments, blocks]
+      end
+
+      def appraise_call?(node)
+        PrismUtils.block_call_to?(node, :appraise)
+      end
+
+      def extract_appraise_name(node)
+        return unless node.is_a?(Prism::CallNode)
+        # Use PrismUtils for extracting literal values
+        PrismUtils.extract_literal_value(node.arguments&.arguments&.first)
+      end
+
+      def merge_preambles(tmpl_comments, dest_comments)
+        tmpl_lines = tmpl_comments.map { |c| c.slice.strip }
+        dest_lines = dest_comments.map { |c| c.slice.strip }
+
+        # Remove magic comments from dest if template has them
+        magic_pattern = /^#.*frozen_string_literal/
+        if tmpl_lines.any? { |line| line.match?(magic_pattern) }
+          dest_lines.reject! { |line| line.match?(magic_pattern) }
+        end
+
+        # Merge unique lines (case-insensitive), template first
+        merged = []
+        seen = Set.new
+
+        (tmpl_lines + dest_lines).each do |line|
+          normalized = line.downcase
+          unless seen.include?(normalized)
+            merged << line
+            seen << normalized
+          end
+        end
+
+        merged
+      end
+
+      def extract_block_header(node, source_lines, previous_blocks)
+        # Get the line number where this block starts (1-indexed from Prism)
+        begin_line = node.location.start_line
+
+        # Find the end of the previous block or start of file
+        min_line = if previous_blocks.empty?
+          1
+        else
+          previous_blocks.last[:node].location.end_line + 1
+        end
+
+        # Convert to 0-indexed and look at the line before the block
+        check_line = begin_line - 2  # e.g., if block is on line 2 (1-indexed), check line 0 (0-indexed, which is line 1 in file)
+
+        # Look backwards from the block start to find contiguous comment lines
+        header_lines = []
+
+        while check_line >= 0 && (check_line + 1) >= min_line
+          line = source_lines[check_line]
+          break unless line
+
+          # Stop at empty line
+          if line.strip.empty?
+            break
+          elsif line.lstrip.start_with?("#")
+            header_lines.unshift(line)
+            check_line -= 1
+          else
+            # Non-comment, non-blank line - stop
+            break
+          end
+        end
+
+        header_lines.join
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__) if defined?(Kettle::Dev.debug_error)
+        ""
+      end
+
+      def merge_blocks(template_blocks, dest_blocks, tmpl_result, dest_result)
+        merged = []
+        dest_by_name = dest_blocks.each_with_object({}) { |b, h| h[b[:name]] = b }
+        template_names = template_blocks.map { |b| b[:name] }.to_set
+
+        # Track which dest blocks we've already placed
+        placed_dest = Set.new
+
+        # For each template block, merge it and insert any dest-only blocks that come before it
+        template_blocks.each_with_index do |tmpl_block, idx|
+          name = tmpl_block[:name]
+
+          # Find dest-only blocks that should come before this template block
+          # (i.e., blocks that appear in dest before this shared block)
+          if idx == 0 || dest_by_name[name]
+            # For first template block or when we have a dest version of this block,
+            # check if there are dest-only blocks to insert before it
+            dest_blocks.each do |db|
+              next if template_names.include?(db[:name])
+              next if placed_dest.include?(db[:name])
+
+              # Check if this dest-only block comes before current shared block in dest
+              dest_idx_of_shared = dest_blocks.index { |b| b[:name] == name }
+              dest_idx_of_only = dest_blocks.index { |b| b[:name] == db[:name] }
+
+              if dest_idx_of_only && dest_idx_of_shared && dest_idx_of_only < dest_idx_of_shared
+                merged << db
+                placed_dest << db[:name]
+              end
+            end
+          end
+
+          # Now add the template block (merged or template-only)
+          dest_block = dest_by_name[name]
+          if dest_block
+            # Merge this block
+            merged_header = merge_block_headers(tmpl_block[:header], dest_block[:header])
+            merged_statements = merge_block_statements(
+              tmpl_block[:node].block.body,
+              dest_block[:node].block.body,
+              dest_result,
+            )
+            merged << {
+              name: name,
+              header: merged_header,
+              node: tmpl_block[:node],
+              statements: merged_statements,
+            }
+            placed_dest << name
+          else
+            # Template-only block
+            merged << tmpl_block
+          end
+        end
+
+        # Add any remaining destination-only blocks that haven't been placed
+        dest_blocks.each do |dest_block|
+          next if placed_dest.include?(dest_block[:name])
+          next if template_names.include?(dest_block[:name])
+          merged << dest_block
+        end
+
+        merged
+      end
+
+      def merge_block_headers(tmpl_header, dest_header)
+        tmpl_lines = tmpl_header.to_s.lines.map(&:strip).reject(&:empty?)
+        dest_lines = dest_header.to_s.lines.map(&:strip).reject(&:empty?)
+
+        # Merge without duplicates (case-insensitive comparison), template first
+        merged = []
+        seen = Set.new
+
+        (tmpl_lines + dest_lines).each do |line|
+          normalized = line.downcase
+          unless seen.include?(normalized)
+            merged << line
+            seen << normalized
+          end
+        end
+
+        return "" if merged.empty?
+        merged.join("\n") + "\n"
+      end
+
+      def merge_block_statements(tmpl_body, dest_body, dest_result)
+        tmpl_stmts = PrismUtils.extract_statements(tmpl_body)
+        dest_stmts = PrismUtils.extract_statements(dest_body)
+
+        # Build statement keys for both
+        tmpl_keys = Set.new
+        tmpl_key_to_node = {}
+        tmpl_stmts.each do |stmt|
+          key = statement_key(stmt)
+          if key
+            tmpl_keys << key
+            tmpl_key_to_node[key] = stmt
+          end
+        end
+
+        dest_keys = Set.new
+        dest_stmts.each do |stmt|
+          key = statement_key(stmt)
+          dest_keys << key if key
+        end
+
+        # Process dest statements in order, preserving their position and comments
+        merged = []
+        dest_stmts.each_with_index do |dest_stmt, idx|
+          dest_key = statement_key(dest_stmt)
+
+          if dest_key && tmpl_keys.include?(dest_key)
+            # Shared statement - use template version but preserve dest position
+            # Add it with no comments (template version is canonical)
+            merged << {node: tmpl_key_to_node[dest_key], inline_comments: [], leading_comments: [], shared: true, key: dest_key}
+          else
+            # Dest-only statement - preserve with all comments
+            inline_comments = PrismUtils.inline_comments_for_node(dest_result, dest_stmt)
+
+            prev_stmt = (idx > 0) ? dest_stmts[idx - 1] : nil
+            leading_comments = PrismUtils.find_leading_comments(dest_result, dest_stmt, prev_stmt, dest_body)
+
+            merged << {node: dest_stmt, inline_comments: inline_comments, leading_comments: leading_comments, shared: false}
+          end
+        end
+
+        # Add template-only statements (those not in dest) at the end
+        tmpl_stmts.each do |tmpl_stmt|
+          tmpl_key = statement_key(tmpl_stmt)
+          unless tmpl_key && dest_keys.include?(tmpl_key)
+            merged << {node: tmpl_stmt, inline_comments: [], leading_comments: [], shared: false}
+          end
+        end
+
+        # Clean up - remove the tracking fields
+        merged.each do |item|
+          item.delete(:shared)
+          item.delete(:key)
+        end
+
+        merged
+      end
+
+      def statement_key(node)
+        # Use PrismUtils for statement key generation with Appraisals-specific tracked methods
+        PrismUtils.statement_key(node, tracked_methods: TRACKED_METHODS)
+      end
+
+      def build_output(preamble_lines, blocks)
+        output = []
+
+        # Add preamble
+        preamble_lines.each { |line| output << line }
+        output << "" unless preamble_lines.empty?
+
+        # Add blocks
+        blocks.each do |block|
+          # Add block header (no blank line before it)
+          header = block[:header]
+          if header && !header.strip.empty?
+            output << header.rstrip
+          end
+
+          # Add appraise call - using parentheses and curly braces format
+          name = block[:name]
+          output << "appraise(\"#{name}\") {"
+
+          # Add statements
+          statements = block[:statements] || extract_original_statements(block[:node])
+          statements.each do |stmt_info|
+            # Add any leading comments before this statement
+            leading = stmt_info[:leading_comments] || []
+            leading.each do |comment|
+              output << "  #{comment.slice.strip}"
+            end
+
+            node = stmt_info[:node]
+            # Normalize the statement to use parentheses
+            line = normalize_statement(node)
+
+            inline = stmt_info[:inline_comments] || []
+            inline_str = inline.map { |c| c.slice.strip }.join(" ")
+            output << "  #{line}#{" #{inline_str}" unless inline_str.empty?}"
+          end
+
+          output << "}"
+          output << ""
+        end
+
+        output.join("\n").strip + "\n"
+      end
+
+      def normalize_statement(node)
+        # Use PrismUtils for normalizing call nodes
+        return PrismUtils.node_to_source(node) unless node.is_a?(Prism::CallNode)
+        PrismUtils.normalize_call_node(node)
+      end
+
+      def normalize_argument(arg)
+        # Use PrismUtils for argument normalization
+        PrismUtils.normalize_argument(arg)
+      end
+
+      def extract_original_statements(node)
+        body = node.block&.body
+        return [] unless body
+
+        statements = body.is_a?(Prism::StatementsNode) ? body.body : [body]
+        statements.compact.map { |stmt| {node: stmt, inline_comments: [], leading_comments: []} }
+      end
+    end
+  end
+end

data/lib/kettle/dev/changelog_cli.rb

@@ -2,14 +2,27 @@
 
 module Kettle
   module Dev
+    # CLI for updating CHANGELOG.md with new version sections
+    #
+    # Automatically extracts unreleased changes, formats them into a new version section,
+    # includes coverage and YARD stats, and updates link references.
     class ChangelogCLI
       UNRELEASED_SECTION_HEADING = "[Unreleased]:"
+
+      # Initialize the changelog CLI
+      # Sets up paths for CHANGELOG.md and coverage.json
       def initialize
         @root = Kettle::Dev::CIHelpers.project_root
         @changelog_path = File.join(@root, "CHANGELOG.md")
         @coverage_path = File.join(@root, "coverage", "coverage.json")
       end
 
+      # Main entry point to update CHANGELOG.md
+      #
+      # Detects current version, extracts unreleased changes, formats them into
+      # a new version section with coverage/YARD stats, and updates all link references.
+      #
+      # @return [void]
       def run
         version = Kettle::Dev::Versioning.detect_version(@root)
         today = Time.now.strftime("%Y-%m-%d")

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