kettle-dev 1.0.10 → 1.0.11

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "kettle/dev/exit_adapter"
+require "kettle/dev/input_adapter"
 
 module Kettle
   module Dev
@@ -34,7 +35,8 @@ module Kettle
           meta = helpers.gemspec_metadata(project_root)
           gem_name = meta[:gem_name]
           min_ruby = meta[:min_ruby]
-          gh_org = meta[:gh_org]
+          forge_org = meta[:forge_org] || meta[:gh_org]
+          funding_org = meta[:funding_org] || forge_org
           entrypoint_require = meta[:entrypoint_require]
           namespace = meta[:namespace]
           namespace_shield = meta[:namespace_shield]
@@ -56,14 +58,14 @@ module Kettle
               if File.basename(rel) == "FUNDING.yml"
                 helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
                   c = content.dup
-                  c = c.gsub(/^open_collective:\s+.*$/i) { |line| gh_org ? "open_collective: #{gh_org}" : line }
+                  c = c.gsub(/^open_collective:\s+.*$/i) { |line| funding_org ? "open_collective: #{funding_org}" : line }
                   if gem_name && !gem_name.empty?
                     c = c.gsub(/^tidelift:\s+.*$/i, "tidelift: rubygems/#{gem_name}")
                   end
                   # Also apply common replacements for org/gem/namespace/shields
                   helpers.apply_common_replacements(
                     c,
-                    gh_org: gh_org,
+                    org: forge_org,
                     gem_name: gem_name,
                     namespace: namespace,
                     namespace_shield: namespace_shield,
@@ -74,7 +76,7 @@ module Kettle
                 helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
                   helpers.apply_common_replacements(
                     content,
-                    gh_org: gh_org,
+                    org: forge_org,
                     gem_name: gem_name,
                     namespace: namespace,
                     namespace_shield: namespace_shield,
@@ -163,9 +165,9 @@ module Kettle
             end
           end
 
-          # 6) .env.local special case: never overwrite project .env.local; copy template as .env.local.example
+          # 6) .env.local special case: never read or touch .env.local from source; only copy .env.local.example to .env.local.example
           begin
-            envlocal_src = helpers.prefer_example(File.join(gem_checkout_root, ".env.local"))
+            envlocal_src = File.join(gem_checkout_root, ".env.local.example")
             envlocal_dest = File.join(project_root, ".env.local.example")
             if File.exist?(envlocal_src)
               helpers.copy_file_with_prompt(envlocal_src, envlocal_dest, allow_create: true, allow_replace: true)
@@ -201,16 +203,58 @@ module Kettle
             .junie/guidelines-rbs.md
           ]
 
+          # Snapshot existing README content once (for H1 prefix preservation after write)
+          existing_readme_before = begin
+            path = File.join(project_root, "README.md")
+            File.file?(path) ? File.read(path) : nil
+          rescue StandardError
+            nil
+          end
+
           files_to_copy.each do |rel|
             src = helpers.prefer_example(File.join(gem_checkout_root, rel))
             dest = File.join(project_root, rel)
             next unless File.exist?(src)
             if File.basename(rel) == "README.md"
+              # Precompute destination README H1 prefix (emoji(s) or first grapheme) before any overwrite occurs
+              prev_readme = File.exist?(dest) ? File.read(dest) : nil
+              begin
+                if prev_readme
+                  first_h1_prev = prev_readme.lines.find { |ln| ln =~ /^#\s+/ }
+                  if first_h1_prev
+                    require "kettle/emoji_regex"
+                    emoji_re = Kettle::EmojiRegex::REGEX
+                    tail = first_h1_prev.sub(/^#\s+/, "")
+                    # Extract consecutive leading emoji graphemes
+                    out = +""
+                    s = tail.dup
+                    loop do
+                      cluster = s[/\A\X/u]
+                      break if cluster.nil? || cluster.empty?
+                      if emoji_re.match?(cluster)
+                        out << cluster
+                        s = s[cluster.length..-1].to_s
+                      else
+                        break
+                      end
+                    end
+                    if !out.empty?
+                      out
+                    else
+                      # Fallback to first grapheme
+                      tail[/\A\X/u]
+                    end
+                  end
+                end
+              rescue StandardError
+                # ignore, leave dest_preserve_prefix as nil
+              end
+
               helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
                 # 1) Do token replacements on the template content (org/gem/namespace/shields)
                 c = helpers.apply_common_replacements(
                   content,
-                  gh_org: gh_org,
+                  org: forge_org,
                   gem_name: gem_name,
                   namespace: namespace,
                   namespace_shield: namespace_shield,
@@ -219,38 +263,75 @@ module Kettle
 
                 # 2) Merge specific sections from destination README, if present
                 begin
-                  dest_existing = File.exist?(dest) ? File.read(dest) : nil
+                  dest_existing = prev_readme
+
+                  # Parse Markdown headings while ignoring fenced code blocks (``` ... ```)
+                  build_sections = lambda do |md|
+                    return {lines: [], sections: [], line_count: 0} unless md
+                    lines = md.split("\n", -1)
+                    line_count = lines.length
 
-                  # Helper to parse markdown sections at any heading level (#, ##, ###, ...)
-                  parse_sections = lambda do |md|
                     sections = []
-                    return sections unless md
-                    lines = md.split("\n", -1) # keep trailing empty lines
-                    indices = []
+                    in_code = false
+                    fence_re = /^\s*```/ # start or end of fenced block
+
                     lines.each_with_index do |ln, i|
-                      indices << i if ln =~ /^#+\s+.+/
+                      if ln =~ fence_re
+                        in_code = !in_code
+                        next
+                      end
+                      next if in_code
+                      if (m = ln.match(/^(#+)\s+.+/))
+                        level = m[1].length
+                        title = ln.sub(/^#+\s+/, "")
+                        base = title.sub(/\A[^\p{Alnum}]+/u, "").strip.downcase
+                        sections << {start: i, level: level, heading: ln, base: base}
+                      end
                     end
-                    indices << lines.length
-                    indices.each_cons(2) do |start_i, nxt|
-                      heading = lines[start_i]
-                      body_lines = lines[(start_i + 1)...nxt] || []
-                      title = heading.sub(/^#+\s+/, "")
-                      # Normalize by removing leading emoji/non-alnum and extra spaces
-                      base = title.sub(/\A[^\p{Alnum}]+/u, "").strip.downcase
-                      sections << {start: start_i, stop: nxt - 1, heading: heading, body: body_lines.join("\n"), base: base}
+
+                    # Compute stop indices based on next heading of same or higher level
+                    sections.each_with_index do |sec, i|
+                      j = i + 1
+                      stop = line_count - 1
+                      while j < sections.length
+                        if sections[j][:level] <= sec[:level]
+                          stop = sections[j][:start] - 1
+                          break
+                        end
+                        j += 1
+                      end
+                      sec[:stop_to_next_any] = stop
+                      body_lines_any = lines[(sec[:start] + 1)..stop] || []
+                      sec[:body_to_next_any] = body_lines_any.join("\n")
+                    end
+
+                    {lines: lines, sections: sections, line_count: line_count}
+                  end
+
+                  # Helper: Compute the branch end (inclusive) for a section at index i
+                  branch_end_index = lambda do |sections_arr, i, total_lines|
+                    current = sections_arr[i]
+                    j = i + 1
+                    while j < sections_arr.length
+                      return sections_arr[j][:start] - 1 if sections_arr[j][:level] <= current[:level]
+                      j += 1
                     end
-                    {lines: lines, sections: sections}
+                    total_lines - 1
                   end
 
-                  # Parse src (c) and dest
-                  src_parsed = parse_sections.call(c)
-                  dest_parsed = parse_sections.call(dest_existing)
+                  src_parsed = build_sections.call(c)
+                  dest_parsed = build_sections.call(dest_existing)
 
-                  # Build lookup for destination sections by base title
+                  # Build lookup for destination sections by base title, using full branch body (to next heading of same or higher level)
                   dest_lookup = {}
                   if dest_parsed && dest_parsed[:sections]
-                    dest_parsed[:sections].each do |s|
-                      dest_lookup[s[:base]] = s[:body]
+                    dest_parsed[:sections].each_with_index do |s, idx|
+                      base = s[:base]
+                      # Only set once (first occurrence wins)
+                      next if dest_lookup.key?(base)
+                      be = branch_end_index.call(dest_parsed[:sections], idx, dest_parsed[:line_count])
+                      body_lines = dest_parsed[:lines][(s[:start] + 1)..be] || []
+                      dest_lookup[base] = {body_branch: body_lines.join("\n"), level: s[:level]}
                     end
                   end
 
@@ -263,17 +344,21 @@ module Kettle
                   end
                   targets = ["synopsis", "configuration", "basic usage"] + note_bases
 
-                  # Replace matching sections in src
+                  # Replace matching sections in src using full branch ranges
                   if src_parsed && src_parsed[:sections] && !src_parsed[:sections].empty?
                     lines = src_parsed[:lines].dup
-                    # Iterate over src sections; when base is in targets, rewrite its body
-                    src_parsed[:sections].reverse_each do |sec|
+                    # Iterate in reverse to keep indices valid
+                    src_parsed[:sections].reverse_each.with_index do |sec, rev_i|
                       next unless targets.include?(sec[:base])
-                      new_body = dest_lookup.fetch(sec[:base], "\n\n")
+                      # Determine branch range in src for this section
+                      # rev_i is reverse index; compute forward index
+                      i = src_parsed[:sections].length - 1 - rev_i
+                      src_end = branch_end_index.call(src_parsed[:sections], i, src_parsed[:line_count])
+                      dest_entry = dest_lookup[sec[:base]]
+                      new_body = dest_entry ? dest_entry[:body_branch] : "\n\n"
                       new_block = [sec[:heading], new_body].join("\n")
-                      # Replace the range from start+0 to stop with new_block lines
                       range_start = sec[:start]
-                      range_end = sec[:stop]
+                      range_end = src_end
                       # Remove old range
                       lines.slice!(range_start..range_end)
                       # Insert new block (split preserves potential empty tail)
@@ -283,46 +368,22 @@ module Kettle
                     c = lines.join("\n")
                   end
 
-                  # 3) Preserve first H1 emojis from destination README, if any
+                  # 3) Preserve entire H1 line from destination README, if any
                   begin
-                    emoji_re = Kettle::EmojiRegex::REGEX
-
-                    dest_emojis = nil
                     if dest_existing
-                      first_h1_dest = dest_existing.lines.find { |ln| ln =~ /^#\s+/ }
-                      if first_h1_dest
-                        after = first_h1_dest.sub(/^#\s+/, "")
-                        emojis = +""
-                        while after =~ /\A#{emoji_re.source}/u
-                          # Capture the entire grapheme cluster for the emoji (handles VS16/ZWJ sequences)
-                          cluster = after[/\A\X/u]
-                          emojis << cluster
-                          after = after[cluster.length..-1].to_s
+                      dest_h1 = dest_existing.lines.find { |ln| ln =~ /^#\s+/ }
+                      if dest_h1
+                        lines_new = c.split("\n", -1)
+                        src_h1_idx = lines_new.index { |ln| ln =~ /^#\s+/ }
+                        if src_h1_idx
+                          # Replace the entire H1 line with the destination's H1 exactly
+                          lines_new[src_h1_idx] = dest_h1.chomp
+                          c = lines_new.join("\n")
                         end
-                        dest_emojis = emojis unless emojis.empty?
-                      end
-                    end
-
-                    if dest_emojis && !dest_emojis.empty?
-                      lines_new = c.split("\n", -1)
-                      idx = lines_new.index { |ln| ln =~ /^#\s+/ }
-                      if idx
-                        rest = lines_new[idx].sub(/^#\s+/, "")
-                        # Remove any leading emojis from the H1 by peeling full grapheme clusters
-                        rest_wo_emoji = begin
-                          tmp = rest.dup
-                          while tmp =~ /\A#{emoji_re.source}/u
-                            cluster = tmp[/\A\X/u]
-                            tmp = tmp[cluster.length..-1].to_s
-                          end
-                          tmp.sub(/\A\s+/, "")
-                        end
-                        lines_new[idx] = ["#", dest_emojis, rest_wo_emoji].join(" ").gsub(/\s+/, " ").sub(/^#\s+/, "# ")
-                        c = lines_new.join("\n")
                       end
                     end
                   rescue StandardError
-                    # ignore emoji preservation errors
+                    # ignore H1 preservation errors
                   end
                 rescue StandardError
                   # Best effort; if anything fails, keep c as-is
@@ -332,20 +393,54 @@ module Kettle
               end
             elsif ["CHANGELOG.md", "CITATION.cff", "CONTRIBUTING.md", ".opencollective.yml", ".junie/guidelines.md"].include?(rel)
               helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true) do |content|
-                helpers.apply_common_replacements(
+                c = helpers.apply_common_replacements(
                   content,
-                  gh_org: gh_org,
+                  org: ((File.basename(rel) == ".opencollective.yml") ? funding_org : forge_org),
                   gem_name: gem_name,
                   namespace: namespace,
                   namespace_shield: namespace_shield,
                   gem_shield: gem_shield,
                 )
+                # Retain whitespace everywhere, except collapse repeated whitespace in CHANGELOG release headers only
+                if File.basename(rel) == "CHANGELOG.md"
+                  lines = c.split("\n", -1)
+                  lines.map! do |ln|
+                    if ln =~ /^##\s+\[.*\]/
+                      ln.gsub(/[ \t]+/, " ")
+                    else
+                      ln
+                    end
+                  end
+                  c = lines.join("\n")
+                end
+                c
               end
             else
               helpers.copy_file_with_prompt(src, dest, allow_create: true, allow_replace: true)
             end
           end
 
+          # Post-process README H1 preservation using snapshot (replace entire H1 line)
+          begin
+            if existing_readme_before
+              readme_path = File.join(project_root, "README.md")
+              if File.file?(readme_path)
+                prev = existing_readme_before
+                newc = File.read(readme_path)
+                prev_h1 = prev.lines.find { |ln| ln =~ /^#\s+/ }
+                lines = newc.split("\n", -1)
+                cur_h1_idx = lines.index { |ln| ln =~ /^#\s+/ }
+                if prev_h1 && cur_h1_idx
+                  # Replace the entire H1 line with the previous README's H1 exactly
+                  lines[cur_h1_idx] = prev_h1.chomp
+                  File.open(readme_path, "w") { |f| f.write(lines.join("\n")) }
+                end
+              end
+            end
+          rescue StandardError
+            # ignore post-processing errors
+          end
+
           # 7b) certs/pboling.pem
           begin
             cert_src = File.join(gem_checkout_root, "certs", "pboling.pem")
@@ -415,8 +510,15 @@ module Kettle
               puts "  [l] Local to this project (#{File.join(project_root, ".git-hooks")})"
               puts "  [g] Global for this user (#{File.join(ENV["HOME"], ".git-hooks")})"
               puts "  [s] Skip copying"
-              print("Choose (l/g/s) [l]: ")
-              choice = $stdin.gets&.strip
+              # Allow non-interactive selection via environment
+              # Precedence: CLI switch (hook_templates) > KETTLE_DEV_HOOK_TEMPLATES > prompt
+              env_choice = ENV["hook_templates"]
+              env_choice = ENV["KETTLE_DEV_HOOK_TEMPLATES"] if env_choice.nil? || env_choice.strip.empty?
+              choice = env_choice&.strip
+              unless choice && !choice.empty?
+                print("Choose (l/g/s) [l]: ")
+                choice = Kettle::Dev::InputAdapter.gets&.strip
+              end
               choice = "l" if choice.nil? || choice.empty?
               dest_dir = case choice.downcase
               when "g", "global" then File.join(ENV["HOME"], ".git-hooks")

data/lib/kettle/dev/template_helpers.rb

@@ -2,6 +2,8 @@
 
 # External stdlibs
 require "find"
+# Internal
+require "kettle/dev/input_adapter"
 
 module Kettle
   module Dev
@@ -38,7 +40,7 @@ module Kettle
           return true
         end
         print("#{prompt} #{default ? "[Y/n]" : "[y/N]"}: ")
-        ans = $stdin.gets&.strip
+        ans = Kettle::Dev::InputAdapter.gets&.strip
         ans = "" if ans.nil?
         if default
           ans.empty? || ans =~ /\Ay(es)?\z/i
@@ -175,6 +177,21 @@ module Kettle
                 FileUtils.mkdir_p(target)
               else
                 FileUtils.mkdir_p(File.dirname(target))
+                if File.exist?(target)
+                  # Skip only if contents are identical. If source and target paths are the same,
+                  # avoid FileUtils.cp (which raises) and do an in-place rewrite to satisfy "copy".
+                  begin
+                    if FileUtils.compare_file(path, target)
+                      next
+                    elsif path == target
+                      data = File.binread(path)
+                      File.open(target, "wb") { |f| f.write(data) }
+                      next
+                    end
+                  rescue StandardError
+                    # ignore compare errors; fall through to copy
+                  end
+                end
                 FileUtils.cp(path, target)
               end
             end
@@ -194,6 +211,21 @@ module Kettle
               FileUtils.mkdir_p(target)
             else
               FileUtils.mkdir_p(File.dirname(target))
+              if File.exist?(target)
+                # Skip only if contents are identical. If source and target paths are the same,
+                # avoid FileUtils.cp (which raises) and do an in-place rewrite to satisfy "copy".
+                begin
+                  if FileUtils.compare_file(path, target)
+                    next
+                  elsif path == target
+                    data = File.binread(path)
+                    File.open(target, "wb") { |f| f.write(data) }
+                    next
+                  end
+                rescue StandardError
+                  # ignore compare errors; fall through to copy
+                end
+              end
               FileUtils.cp(path, target)
             end
           end
@@ -204,15 +236,15 @@ module Kettle
 
       # Apply common token replacements used when templating text files
       # @param content [String]
-      # @param gh_org [String, nil]
+      # @param org [String, nil]
       # @param gem_name [String]
       # @param namespace [String]
       # @param namespace_shield [String]
       # @param gem_shield [String]
       # @return [String]
-      def apply_common_replacements(content, gh_org:, gem_name:, namespace:, namespace_shield:, gem_shield:)
+      def apply_common_replacements(content, org:, gem_name:, namespace:, namespace_shield:, gem_shield:)
         c = content.dup
-        c = c.gsub("kettle-rb", gh_org.to_s) if gh_org && !gh_org.empty?
+        c = c.gsub("kettle-rb", org.to_s) if org && !org.empty?
         if gem_name && !gem_name.empty?
           # Replace occurrences of the template gem name in text, including inside
           # markdown reference labels like [🖼️kettle-dev] and identifiers like kettle-dev-i
@@ -248,15 +280,15 @@ module Kettle
           end
         end
         gh_match = homepage_val&.match(%r{github\.com/([^/]+)/([^/]+)}i)
-        gh_org = gh_match && gh_match[1]
+        forge_org = gh_match && gh_match[1]
         gh_repo = gh_match && gh_match[2]&.sub(/\.git\z/, "")
-        if gh_org.nil?
+        if forge_org.nil?
           begin
             origin_out = IO.popen(["git", "-C", root.to_s, "remote", "get-url", "origin"], &:read)
             origin_out = origin_out.read if origin_out.respond_to?(:read)
             origin_url = origin_out.to_s.strip
             if (m = origin_url.match(%r{github\.com[/:]([^/]+)/([^/]+)}i))
-              gh_org = m[1]
+              forge_org = m[1]
               gh_repo = m[2]&.sub(/\.git\z/, "")
             end
           rescue StandardError
@@ -272,12 +304,33 @@ module Kettle
         entrypoint_require = gem_name.to_s.tr("-", "/")
         gem_shield = gem_name.to_s.gsub("-", "--").gsub("_", "__")
 
+        # Determine funding_org independently of forge_org (GitHub org)
+        funding_org = ENV["FUNDING_ORG"].to_s.strip
+        funding_org = ENV["OPENCOLLECTIVE_ORG"].to_s.strip if funding_org.empty?
+        funding_org = ENV["OPENCOLLECTIVE_HANDLE"].to_s.strip if funding_org.empty?
+        if funding_org.empty?
+          begin
+            oc_path = File.join(root.to_s, ".opencollective.yml")
+            if File.file?(oc_path)
+              txt = File.read(oc_path)
+              if (m = txt.match(/\borg:\s*([\w\-]+)/i))
+                funding_org = m[1].to_s
+              end
+            end
+          rescue StandardError
+            # ignore
+          end
+        end
+        funding_org = forge_org.to_s if funding_org.to_s.empty?
+
         {
           gemspec_path: gemspec_path,
           gem_name: gem_name,
           min_ruby: min_ruby,
           homepage: homepage_val,
-          gh_org: gh_org,
+          gh_org: forge_org, # Backward compat: keep old key synonymous with forge_org
+          forge_org: forge_org,
+          funding_org: funding_org,
           gh_repo: gh_repo,
           namespace: namespace,
           namespace_shield: namespace_shield,

data/lib/kettle/dev/version.rb

@@ -6,7 +6,7 @@ module Kettle
     module Version
       # The gem version.
       # @return [String]
-      VERSION = "1.0.10"
+      VERSION = "1.0.11"
     end
   end
 end

data/lib/kettle/dev/versioning.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Dev
+    # Shared helpers for version detection and bump classification.
+    module Versioning
+      module_function
+
+      # Detects a unique VERSION constant declared under lib/**/version.rb
+      # @param root [String] project root
+      # @return [String] version string
+      def detect_version(root)
+        candidates = Dir[File.join(root, "lib", "**", "version.rb")]
+        abort!("Could not find version.rb under lib/**.") if candidates.empty?
+        versions = candidates.map do |path|
+          content = File.read(path)
+          m = content.match(/VERSION\s*=\s*(["'])([^"']+)\1/)
+          next unless m
+          m[2]
+        end.compact
+        abort!("VERSION constant not found in #{root}/lib/**/version.rb") if versions.none?
+        abort!("Multiple VERSION constants found to be out of sync (#{versions.inspect}) in #{root}/lib/**/version.rb") unless versions.uniq.length == 1
+        versions.first
+      end
+
+      # Classify the bump type from prev -> cur.
+      # EPIC is a MAJOR > 1000.
+      # @param prev [String] previous released version
+      # @param cur [String] current version (from version.rb)
+      # @return [Symbol] one of :epic, :major, :minor, :patch, :same, :downgrade
+      def classify_bump(prev, cur)
+        pv = Gem::Version.new(prev)
+        cv = Gem::Version.new(cur)
+        return :same if cv == pv
+        return :downgrade if cv < pv
+
+        pmaj, pmin, ppatch = (pv.segments + [0, 0, 0])[0, 3]
+        cmaj, cmin, cpatch = (cv.segments + [0, 0, 0])[0, 3]
+
+        if cmaj > pmaj
+          return :epic if cmaj && cmaj > 1000
+          :major
+        elsif cmin > pmin
+          :minor
+        elsif cpatch > ppatch
+          :patch
+        else
+          # Fallback; should be covered by :same above, but in case of weird segment shapes
+          :same
+        end
+      end
+
+      # Whether MAJOR is an EPIC version (strictly > 1000)
+      # @param major [Integer]
+      # @return [Boolean]
+      def epic_major?(major)
+        major && major > 1000
+      end
+
+      # Abort via ExitAdapter if available; otherwise Kernel.abort
+      # @param msg [String]
+      # @return [void]
+      def abort!(msg)
+        Kettle::Dev::ExitAdapter.abort(msg)
+      end
+    end
+  end
+end

data/sig/kettle/dev/input_adapter.rbs

@@ -0,0 +1,8 @@
+module Kettle
+  module Dev
+    module InputAdapter
+      def self.gets: (*untyped args) -> String?
+      def self.readline: (*untyped args) -> String
+    end
+  end
+end

data/sig/kettle/dev/template_helpers.rbs

@@ -44,7 +44,7 @@ module Kettle
       # Apply common token replacements used when templating text files
       def self.apply_common_replacements: (
         String content,
-        gh_org: String?,
+        org: String?,
         gem_name: String,
         namespace: String,
         namespace_shield: String,
@@ -59,6 +59,8 @@ module Kettle
         min_ruby: String,
         homepage: String,
         gh_org: String?,
+        forge_org: String?,
+        funding_org: String?,
         gh_repo: String?,
         namespace: String,
         namespace_shield: String,