kettle-dev 1.1.59 → 1.2.0

data/lib/kettle/dev/rakelib/spec_test.rake

@@ -12,7 +12,9 @@ begin
     t.test_files = FileList["test/**/*test*.rb"]
     t.verbose = true
   end
-  Kettle::Dev.register_default("test")
+  # The test task is invoked by the coverage task, so of the two, (i.e., when outside CI),
+  #   only coverage should be registered as default.
+  Kettle::Dev.register_default("test") unless Kettle::Dev.default_registered?("coverage")
 rescue LoadError
   warn("[kettle-dev][spec_test.rake] failed to load rake/testtask") if Kettle::Dev::DEBUGGING
   desc("test task stub")
@@ -21,34 +23,82 @@ rescue LoadError
   end
 end
 
-# Setup RSpec
-begin
-  require "rspec/core/rake_task"
+setup_spec_task = ->(default:) {
+  begin
+    require "rspec/core/rake_task"
 
-  RSpec::Core::RakeTask.new(:spec)
-  # This takes the place of `coverage` task it hasn't been registered yet.
-  Kettle::Dev.register_default("spec") unless Kettle::Dev.default_registered?("coverage")
-rescue LoadError
-  warn("[kettle-dev][spec_test.rake] failed to load rspec/core/rake_task") if Kettle::Dev::DEBUGGING
-  desc("spec task stub")
-  task(:spec) do
-    warn("NOTE: rspec isn't installed, or is disabled for #{RUBY_VERSION} in the current environment")
+    RSpec::Core::RakeTask.new(:spec)
+    if default
+      # This takes the place of the `coverage` task if/when it isn't already registered.
+      # This is because spec and coverage run the same tests
+      # (via the coverage task invoking the test task which invokes the spec task),
+      # so we can't have both in the default task.
+      Kettle::Dev.register_default("spec") unless Kettle::Dev.default_registered?("coverage")
+    end
+  rescue LoadError
+    warn("[kettle-dev][spec_test.rake] failed to load rspec/core/rake_task") if Kettle::Dev::DEBUGGING
+    desc("spec task stub")
+    task(:spec) do
+      warn("NOTE: rspec isn't installed, or is disabled for #{RUBY_VERSION} in the current environment")
+    end
+  end
+}
+
+# Setup RSpec
+if defined?(Kettle::Dev::IS_CI)
+  if Kettle::Dev::IS_CI
+    # then we should not have a coverage task, but do want a spec test.
+    setup_spec_task.call(default: true)
+  else
+    # then we should have a coverage task.
+    # The coverage task will invoke the "test" task, which will invoke the spec task.
+    setup_spec_task.call(default: false)
   end
+else
+  # then we do not have a coverage task setup by this gem, and are not in a coverage context.
+  # So setup a spec test.
+  setup_spec_task.call(default: true)
 end
 
 spec_registered = Kettle::Dev.default_registered?("spec")
 coverage_registered = Kettle::Dev.default_registered?("coverage")
 test_registered = Kettle::Dev.default_registered?("test")
+spec_and_coverage = spec_registered && coverage_registered
 spec_or_coverage = spec_registered || coverage_registered
 
-if spec_or_coverage && !test_registered
-  task test: :spec
-elsif test_registered && !spec_or_coverage
+if test_registered && !spec_or_coverage
   task spec: :test
-elsif test_registered && spec_or_coverage
-  # When we have both tasks registered, make spec run as part of the test task
-  task test: :spec
-else
-  puts "No test task is registered."
+# elsif test_registered && spec_registered
+#   # When we have both tasks registered as default, making spec run as part of test would be redundant.
+#   # task test: :spec
+# elsif test_registered && coverage_registered
+#   # When we have both tasks registered as default, making coverage run as part of test would be circular.
+#   # task test: :coverage
+elsif !test_registered
+  if spec_registered && !coverage_registered
+    puts "Spec task is registered as default task. Creating test task with spec as pre-requisite" if Kettle::Dev::DEBUGGING
+    # If spec is registered as default, it should be invoked by the test task when test is not default,
+    #   because some CI workflows will be configured to run bin/rake test.
+    desc "A test task with spec as prerequisite"
+    task test: :spec
+  elsif coverage_registered && !spec_registered
+    puts "Coverage task is registered as default task, and will call test task, with spec as pre-requisite." if Kettle::Dev::DEBUGGING
+    # If coverage is registered as default, it will invoke test.
+    # We need to make spec a prerequisite of test so that it runs as part of the test task,
+    # which will be invoked by the coverage task.
+    desc "A test task with spec as prerequisite"
+    task test: :spec
+  end
 end
 # rubocop:enable Rake/DuplicateTask
+
+if spec_and_coverage
+  # They should not both be registered as default tasks, as they run the same tests.
+  warn("[kettle-dev][spec_test.rake] both spec and coverage are registered as default tasks!") if Kettle::Dev::DEBUGGING
+elsif test_registered && spec_registered
+  # They should not both be registered as default tasks, as they will be setup to run the same tests.
+  warn("[kettle-dev][spec_test.rake] both test and spec are registered as default tasks!") if Kettle::Dev::DEBUGGING
+elsif test_registered && coverage_registered
+  # They should not both be registered as default tasks, coverage invokes the test task.
+  warn("[kettle-dev][spec_test.rake] both test and coverage are registered as default tasks!") if Kettle::Dev::DEBUGGING
+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