kettle-dev 1.1.60 → 1.2.1

data/lib/kettle/dev/template_helpers.rb

@@ -3,6 +3,7 @@
 # External stdlibs
 require "find"
 require "set"
+require "yaml"
 
 module Kettle
   module Dev
@@ -17,6 +18,12 @@ module Kettle
       # The minimum Ruby supported by setup-ruby GHA
       MIN_SETUP_RUBY = Gem::Version.create("2.3")
 
+      TEMPLATE_MANIFEST_PATH = File.expand_path("../../..", __dir__) + "/template_manifest.yml"
+      RUBY_BASENAMES = %w[Gemfile Rakefile Appraisals Appraisal.root.gemfile .simplecov].freeze
+      RUBY_SUFFIXES = %w[.gemspec .gemfile].freeze
+      RUBY_EXTENSIONS = %w[.rb .rake].freeze
+      @@manifestation = nil
+
       module_function
 
       # Root of the host project where Rake was invoked
@@ -270,52 +277,25 @@ module Kettle
 
         content = File.read(src_path)
         content = yield(content) if block_given?
-        # Final global replacements that must occur AFTER normal replacements
+        # Replace the explicit template token with the literal "kettle-dev"
+        # after upstream/template-specific replacements (i.e. after the yield),
+        # so the token itself is not altered by those replacements.
         begin
           token = "{KETTLE|DEV|GEM}"
           content = content.gsub(token, "kettle-dev") if content.include?(token)
         rescue StandardError => e
           Kettle::Dev.debug_error(e, __method__)
-          # If replacement fails unexpectedly, proceed with content as-is
         end
 
-        # If updating the Appraisals file and a destination already exists,
-        # merge appraise blocks: augment matching blocks with missing gem/eval_gemfile lines,
-        # preserve destination-only blocks and comments/preamble.
-        begin
-          if dest_exists && File.basename(dest_path.to_s) == "Appraisals" && File.file?(dest_path.to_s)
-            existing = begin
-              File.read(dest_path)
-            rescue
-              ""
-            end
-            content = merge_appraisals(content, existing)
-          end
-        rescue StandardError => e
-          Kettle::Dev.debug_error(e, __method__)
-          # On any error, fall back to generated content
-        end
-
-        # If updating a Gemfile or modular .gemfile and the destination already exists,
-        # merge dependency lines from the source into the destination to preserve any
-        # user-defined gem entries. We append missing `gem "name"` lines; we never
-        # alter or remove existing gem lines in the destination.
-        begin
-          if dest_exists
-            dest_str = dest_path.to_s
-            is_gemfile_like = File.basename(dest_str) == "Gemfile" || dest_str.end_with?(".gemfile")
-            if is_gemfile_like && File.file?(dest_str)
-              begin
-                existing = File.read(dest_str)
-                content = merge_gemfile_dependencies(content, existing)
-              rescue StandardError => e
-                Kettle::Dev.debug_error(e, __method__)
-                # If merging fails, fall back to writing generated content
-              end
-            end
+        basename = File.basename(dest_path.to_s)
+        content = apply_appraisals_merge(content, dest_path) if basename == "Appraisals"
+        if basename == "Appraisal.root.gemfile" && File.exist?(dest_path)
+          begin
+            prior = File.read(dest_path)
+            content = merge_gemfile_dependencies(content, prior)
+          rescue StandardError => e
+            Kettle::Dev.debug_error(e, __method__)
           end
-        rescue StandardError => e
-          Kettle::Dev.debug_error(e, __method__)
         end
 
         write_file(dest_path, content)
@@ -342,311 +322,24 @@ module Kettle
       # @return [String] merged content
       def merge_gemfile_dependencies(src_content, dest_content)
         begin
-          gem_re = /^\s*gem\s+['"]([^'"\s]+)['"].*$/
-          # Collect first occurrence of each gem line in source
-          src_gems = {}
-          src_content.each_line do |ln|
-            next if ln.strip.start_with?("#")
-            if (m = ln.match(gem_re))
-              name = m[1]
-              src_gems[name] ||= ln.rstrip
-            end
-          end
-
-          # --- Handle `source` replacement/insertion ---
-          src_source_line = nil
-          src_content.each_line do |ln|
-            next if ln.strip.start_with?("#")
-            if ln =~ /^\s*source\s+['"][^'"]+['"]\s*$/
-              src_source_line = ln.rstrip + "\n"
-              break
-            end
-          end
-
-          dest_lines = dest_content.lines.dup
-
-          if src_source_line
-            dest_source_idx = dest_lines.index do |ln|
-              !ln.strip.start_with?("#") && ln =~ /^\s*source\s+['"][^'"]+['"]\s*$/
-            end
-            if dest_source_idx
-              dest_lines[dest_source_idx] = src_source_line
-            else
-              # Insert after any leading contiguous comment/blank block at top of file
-              insert_idx = 0
-              while insert_idx < dest_lines.length && (dest_lines[insert_idx].strip.empty? || dest_lines[insert_idx].lstrip.start_with?("#"))
-                insert_idx += 1
-              end
-              dest_lines.insert(insert_idx, src_source_line)
-            end
-          end
-
-          # --- Handle `git_source` replacement/insertion ---
-          # Collect non-comment git_source lines from source (preserve order)
-          src_git_lines = src_content.each_line.select { |ln| !ln.strip.start_with?("#") && ln =~ /^\s*git_source\s*\(/ }
-          if src_git_lines.any?
-            # Insert new git_source lines in the same order as they appear in the source
-            # When inserting (not replacing), place them immediately after the source line if present
-            insert_after_source_idx = dest_lines.index { |ln| !ln.strip.start_with?("#") && ln =~ /^\s*source\s+['"][^'"]+['"]\s*$/ }
-
-            # Iterate source git lines in reverse for insertion so order is preserved when inserting at same index
-            src_git_lines.reverse_each do |gln|
-              # Attempt to extract the git_source "name" (handles forms like git_source(:github) or git_source :github)
-              name_match = gln.match(/^\s*git_source\s*\(?\s*:?(\w+)\b/)
-              name = name_match ? name_match[1].to_s : nil
-
-              replaced = false
-              if name
-                # Try to find a git_source in destination with the same name
-                dest_same_idx = dest_lines.index do |dln|
-                  !dln.strip.start_with?("#") && dln =~ /^\s*git_source\s*\(?\s*:?#{Regexp.escape(name)}\b/
-                end
-                if dest_same_idx
-                  dest_lines[dest_same_idx] = gln.rstrip + "\n"
-                  replaced = true
-                end
-              end
-
-              unless replaced
-                # If destination has a github git_source, replace that
-                dest_github_idx = dest_lines.index do |dln|
-                  !dln.strip.start_with?("#") && dln =~ /^\s*git_source\s*\(?\s*:?github\b/
-                end
-                if dest_github_idx
-                  dest_lines[dest_github_idx] = gln.rstrip + "\n"
-                else
-                  # Insert below the source line if present, otherwise at top (after comments)
-                  insert_idx =
-                    if insert_after_source_idx
-                      insert_after_source_idx + 1
-                    else
-                      0
-                    end
-                  dest_lines.insert(insert_idx, gln.rstrip + "\n")
-                end
-              end
-            end
-          end
-
-          # Index existing gems in destination (after potential source/git_source changes)
-          dest_gems = {}
-          dest_lines.join.each_line do |ln|
-            next if ln.strip.start_with?("#")
-            if (m = ln.match(gem_re))
-              dest_gems[m[1]] = true
-            end
-          end
-
-          missing = src_gems.keys.reject { |n| dest_gems.key?(n) }
-          # If nothing to change, return original destination content
-          if missing.empty? && src_source_line.nil? && src_git_lines.empty?
-            return dest_content
-          end
-
-          out = dest_lines.join
-          out << "\n" unless out.end_with?("\n") || out.empty?
-          if missing.any?
-            out << missing.map { |n| src_gems[n] }.join("\n")
-            out << "\n"
-          end
-          out
+          Kettle::Dev::PrismGemfile.merge_gem_calls(src_content.to_s, dest_content.to_s)
         rescue StandardError => e
           Kettle::Dev.debug_error(e, __method__)
           dest_content
         end
       end
 
-      # Merge Appraisals template into existing Appraisals file.
-      # Rules:
-      #  - For each appraise "name" block in template:
-      #     * If destination has same block, ensure all gem/ eval_gemfile lines from template
-      #       exist in destination (append missing just before end), keep other dest lines.
-      #       Use template's contiguous header comment lines (immediately preceding the appraise line)
-      #       if any; otherwise retain destination's header comments.
-      #     * If destination lacks the block, add the full template block (with its header).
-      #  - Preserve destination-only blocks (not present in template) unchanged and after
-      #    the merged template-ordered blocks.
-      #  - Preamble (content before first appraise) comes from template when present, else destination.
-      def merge_appraisals(template_content, dest_content)
-        begin
-          # Helper: extract contiguous leading header lines (comments and blank lines)
-          extract_leading_header = lambda do |text|
-            lines = text.lines
-            header_lines = []
-            idx = 0
-            while idx < lines.length
-              ln = lines[idx]
-              break unless ln.strip.empty? || ln.lstrip.start_with?("#")
-              header_lines << ln
-              idx += 1
-            end
-            body = (idx < lines.length) ? lines[idx..-1].join : ""
-            {header: header_lines.join, body: body}
-          end
-
-          parse_blocks = lambda do |text|
-            lines = text.lines
-            blocks = []
-            i = 0
-            while i < lines.length
-              line = lines[i]
-              if line =~ /^\s*appraise\s+["']([^"']+)["']\s+do\s*$/
-                name = $1
-                # collect header comment lines immediately preceding (contiguous, no blank between comment group and appraise line)
-                header_lines = []
-                j = i - 1
-                while j >= 0
-                  prev = lines[j]
-                  break if prev.strip.empty?
-                  if prev.lstrip.start_with?("#")
-                    header_lines.unshift(prev)
-                    j -= 1
-                  else
-                    break
-                  end
-                end
-                body_lines = []
-                i += 1
-                while i < lines.length
-                  l2 = lines[i]
-                  if l2 =~ /^\s*end\s*$/
-                    end_line = l2
-                    blocks << {
-                      name: name,
-                      header: header_lines.dup,
-                      body: body_lines.dup,
-                      end_line: end_line,
-                      raw_order: blocks.length,
-                      original_indices: (j ? (j + 1)..i : i),
-                    }
-                    break
-                  else
-                    body_lines << l2
-                  end
-                  i += 1
-                end
-              end
-              i += 1
-            end
-            preamble = if blocks.empty?
-              text
-            else
-              # preamble = lines from start up to first block start (exclusive)
-              first_block = blocks.first
-              # Take lines up to first occurrence of the appraise line (supports either quote type)
-              re = /^\s*appraise\s+["']#{Regexp.escape(first_block[:name])}["']\s+do\s*$/
-              idx = lines.index { |l| l =~ re } || 0
-              lines[0...idx].join
-            end
-            {blocks: blocks, preamble: preamble}
-          end
-
-          # Extract leading headers from template and destination and parse their bodies
-          tmpl_parts = extract_leading_header.call(template_content)
-          dest_parts = extract_leading_header.call(dest_content)
-
-          # If the template does not provide a leading header, preserve the destination as-is
-          # so that per-block adjacent header comments (including those at the top of file)
-          # are still parsed and preserved. Only strip the destination leading header when
-          # the template has a leading header to replace it.
-          dest_parse_source = if tmpl_parts[:header].to_s.strip.empty?
-            dest_content
-          else
-            dest_parts[:body]
-          end
-
-          tmpl = parse_blocks.call(tmpl_parts[:body])
-          dest = parse_blocks.call(dest_parse_source)
-          tmpl_blocks = tmpl[:blocks]
-          dest_blocks = dest[:blocks]
-          dest_by_name = dest_blocks.map { |b| [b[:name], b] }.to_h
-
-          merged_blocks_strings = []
-          gem_or_eval_re = /^\s*(?:gem|eval_gemfile)\b/
-
-          tmpl_blocks.each do |tb|
-            if (db = dest_by_name[tb[:name]])
-              # Merge lines
-              existing_lines = db[:body].map(&:rstrip)
-              existing_set = existing_lines.to_set
-              # Collect template gem/eval lines
-              tmpl_needed = tb[:body].select { |l| gem_or_eval_re =~ l }
-              additions = []
-              tmpl_needed.each do |l|
-                line_key = l.rstrip
-                additions << l unless existing_set.include?(line_key)
-              end
-              merged_body = db[:body].dup
-              unless additions.empty?
-                # insert before end (just append; body excludes 'end')
-                merged_body += additions
-              end
-              header = tb[:header].any? ? tb[:header] : db[:header]
-              # If the template provides no leading header and the destination preamble
-              # already ends with this header, skip emitting the header for this block
-              # to avoid duplicating it (it will already be present at the top of the file).
-              header_to_emit = if tmpl_parts[:header].to_s.strip.empty? && !dest[:preamble].to_s.strip.empty? && !header.empty? && dest[:preamble].to_s.end_with?(header.join)
-                []
-              else
-                header
-              end
-              block_text = +""
-              block_text << "\n" unless merged_blocks_strings.empty?
-              header_to_emit.each { |hl| block_text << hl } if header_to_emit.any?
-              block_text << "appraise \"#{tb[:name]}\" do\n"
-              merged_body.each { |bl| block_text << bl }
-              block_text << db[:end_line]
-              merged_blocks_strings << block_text
-              dest_by_name.delete(tb[:name])
-            else
-              # New block from template
-              block_text = +""
-              block_text << "\n" unless merged_blocks_strings.empty?
-              tb[:header].each { |hl| block_text << hl } if tb[:header].any?
-              block_text << "appraise \"#{tb[:name]}\" do\n"
-              tb[:body].each { |bl| block_text << bl }
-              block_text << tb[:end_line]
-              merged_blocks_strings << block_text
-            end
-          end
-          # Append destination-only blocks preserving their original text
-          dest_remaining_order = dest_blocks.select { |b| dest_by_name.key?(b[:name]) }
-          dest_remaining_order.each do |b|
-            block_text = +""
-            block_text << "\n" unless merged_blocks_strings.empty?
-            b[:header].each { |hl| block_text << hl } if b[:header].any?
-            block_text << "appraise \"#{b[:name]}\" do\n"
-            b[:body].each { |bl| block_text << bl }
-            block_text << b[:end_line]
-            merged_blocks_strings << block_text
-          end
-
-          # Build final preamble:
-          # - If template provides a leading header, use that header and then prefer the
-          #   template's body preamble when present, otherwise fall back to the
-          #   destination's body preamble.
-          # - If template does NOT provide a leading header, leave the destination
-          #   preamble (including any leading header/comments) intact.
-          preamble = +""
-          if tmpl_parts[:header].to_s.strip.empty?
-            preamble << dest[:preamble].to_s
-          else
-            body_preamble = tmpl[:preamble].to_s.strip.empty? ? dest[:preamble].to_s : tmpl[:preamble].to_s
-            preamble << tmpl_parts[:header].to_s
-            preamble << body_preamble.to_s
-          end
-
-          out = +""
-          out << preamble unless preamble.nil? || preamble.empty?
-          out << "\n" unless out.end_with?("\n")
-          out << merged_blocks_strings.join
-          out << "\n" unless out.end_with?("\n")
-          out
-        rescue StandardError => e
-          Kettle::Dev.debug_error(e, __method__)
-          # Fallback: prefer destination (user changes) and append template content to allow manual reconciliation
-          dest_content + "\n# --- TEMPLATE APPRAISALS (unmerged) ---\n" + template_content
+      def apply_appraisals_merge(content, dest_path)
+        dest = dest_path.to_s
+        existing = if File.exist?(dest)
+          File.read(dest)
+        else
+          ""
         end
+        Kettle::Dev::PrismAppraisals.merge(content, existing)
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__)
+        content
       end
 
       # Copy a directory tree, prompting before creating or overwriting.
@@ -883,8 +576,8 @@ module Kettle
           # ignore
         end
 
-        # Replace occurrences of the template gem name in text, including inside
-        # markdown reference labels like [🖼️kettle-dev] and identifiers like kettle-dev-i
+        # Replace occurrences of the literal template gem name ("kettle-dev")
+        # with the destination gem name.
         c = c.gsub("kettle-dev", gem_name)
         c = c.gsub(/\bKettle::Dev\b/u, namespace) unless namespace.empty?
         c = c.gsub("Kettle%3A%3ADev", namespace_shield) unless namespace_shield.empty?
@@ -899,6 +592,49 @@ module Kettle
       def gemspec_metadata(root = project_root)
         Kettle::Dev::GemSpecReader.load(root)
       end
+
+      def apply_strategy(content, dest_path)
+        return content unless ruby_template?(dest_path)
+        strategy = strategy_for(dest_path)
+        dest_content = File.exist?(dest_path) ? File.read(dest_path) : ""
+        Kettle::Dev::SourceMerger.apply(strategy: strategy, src: content, dest: dest_content, path: rel_path(dest_path))
+      end
+
+      def manifestation
+        @@manifestation ||= load_manifest
+      end
+
+      def strategy_for(dest_path)
+        relative = rel_path(dest_path)
+        manifestation.find do |entry|
+          File.fnmatch?(entry[:path], relative, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH)
+        end&.fetch(:strategy, :skip) || :skip
+      end
+
+      def rel_path(path)
+        project = project_root.to_s
+        path.to_s.sub(/^#{Regexp.escape(project)}\/?/, "")
+      end
+
+      def ruby_template?(dest_path)
+        base = File.basename(dest_path.to_s)
+        return true if RUBY_BASENAMES.include?(base)
+        return true if RUBY_SUFFIXES.any? { |suffix| base.end_with?(suffix) }
+        ext = File.extname(base)
+        RUBY_EXTENSIONS.include?(ext)
+      end
+
+      def load_manifest
+        raw = YAML.load_file(TEMPLATE_MANIFEST_PATH)
+        raw.map do |entry|
+          {
+            path: entry["path"],
+            strategy: entry["strategy"].to_s.strip.downcase.to_sym,
+          }
+        end
+      rescue Errno::ENOENT
+        []
+      end
     end
   end
 end

data/lib/kettle/dev/version.rb

@@ -6,7 +6,7 @@ module Kettle
     module Version
       # The gem version.
       # @return [String]
-      VERSION = "1.1.60"
+      VERSION = "1.2.1"
 
       module_function
 

data/lib/kettle/dev.rb

@@ -21,8 +21,13 @@ module Kettle
     autoload :GitAdapter, "kettle/dev/git_adapter"
     autoload :GitCommitFooter, "kettle/dev/git_commit_footer"
     autoload :InputAdapter, "kettle/dev/input_adapter"
+    autoload :PrismUtils, "kettle/dev/prism_utils"
+    autoload :PrismGemspec, "kettle/dev/prism_gemspec"
+    autoload :PrismGemfile, "kettle/dev/prism_gemfile"
+    autoload :PrismAppraisals, "kettle/dev/prism_appraisals"
     autoload :ReadmeBackers, "kettle/dev/readme_backers"
     autoload :OpenCollectiveConfig, "kettle/dev/open_collective_config"
+    autoload :SourceMerger, "kettle/dev/source_merger"
     autoload :ReleaseCLI, "kettle/dev/release_cli"
     autoload :PreReleaseCLI, "kettle/dev/pre_release_cli"
     autoload :SetupCLI, "kettle/dev/setup_cli"
@@ -74,15 +79,30 @@ module Kettle
     @defaults = []
 
     class << self
-      # Emit a debug warning for rescued errors when DEBUG=true.
+      # Emit a debug warning for rescued errors when kettle-dev debugging is enabled.
+      # Controlled by KETTLE_DEV_DEBUG=true (or DEBUG=true as fallback).
       # @param error [Exception]
       # @param context [String, Symbol, nil] optional label, often __method__
       # @return [void]
       def debug_error(error, context = nil)
         return unless DEBUGGING
-        ctx = context ? context.to_s : "rescue"
+
+        ctx = context ? context.to_s : "KETTLE-DEV-RESCUE"
         Kernel.warn("[#{ctx}] #{error.class}: #{error.message}")
-      rescue Exception
+      rescue StandardError
+        # never raise from debug logging
+      end
+
+      # Emit a debug log line when kettle-dev debugging is enabled.
+      # Controlled by KETTLE_DEV_DEBUG=true (or DEBUG=true as fallback).
+      # @param msg [String]
+      # @return [void]
+      def debug_log(msg, context = nil)
+        return unless DEBUGGING
+
+        ctx = context ? context.to_s : "KETTLE-DEV-DEBUG"
+        Kernel.warn("[#{ctx}] #{msg}")
+      rescue StandardError
         # never raise from debug logging
       end
 

data/sig/kettle/dev/appraisals_ast_merger.rbs

@@ -0,0 +1,72 @@
+# TypeProf 0.21.11
+
+module Kettle
+  module Dev
+    # AST-driven merger for Appraisals files using Prism
+    module AppraisalsAstMerger
+      TRACKED_METHODS: Array[Symbol]
+
+      # Merge template and destination Appraisals files preserving comments
+      def self.merge: (String template_content, String dest_content) -> String
+
+      # Extract blocks and preamble from parse result
+      def self.extract_blocks: (
+        Prism::ParseResult parse_result,
+        String source_content
+      ) -> [Array[Prism::Comment], Array[Hash[Symbol, untyped]]]
+
+      # Check if node is an appraise call
+      def self.appraise_call?: (Prism::Node node) -> bool
+
+      # Extract appraise block name from node
+      def self.extract_appraise_name: (Prism::Node? node) -> String?
+
+      # Merge preamble comments from template and destination
+      def self.merge_preambles: (
+        Array[Prism::Comment] tmpl_comments,
+        Array[Prism::Comment] dest_comments
+      ) -> Array[String]
+
+      # Extract block header comments
+      def self.extract_block_header: (
+        Prism::Node node,
+        Array[String] source_lines,
+        Array[Hash[Symbol, untyped]] previous_blocks
+      ) -> String
+
+      # Merge blocks from template and destination
+      def self.merge_blocks: (
+        Array[Hash[Symbol, untyped]] tmpl_blocks,
+        Array[Hash[Symbol, untyped]] dest_blocks,
+        Prism::ParseResult tmpl_result,
+        Prism::ParseResult dest_result
+      ) -> Array[Hash[Symbol, untyped]]
+
+      # Merge statements within a block
+      def self.merge_block_statements: (
+        Prism::Node? tmpl_body,
+        Prism::Node? dest_body,
+        Prism::ParseResult dest_result
+      ) -> Array[Hash[Symbol, untyped]]
+
+      # Generate statement key for deduplication
+      def self.statement_key: (Prism::Node node) -> [Symbol, String?]?
+
+      # Build output from preamble and blocks
+      def self.build_output: (
+        Array[String] preamble_lines,
+        Array[Hash[Symbol, untyped]] blocks
+      ) -> String
+
+      # Normalize statement to use parentheses
+      def self.normalize_statement: (Prism::Node node) -> String
+
+      # Normalize argument to canonical format
+      def self.normalize_argument: (Prism::Node arg) -> String
+
+      # Extract original statements from node
+      def self.extract_original_statements: (Prism::Node node) -> Array[Hash[Symbol, untyped]]
+    end
+  end
+end
+

data/sig/kettle/dev/changelog_cli.rbs

@@ -0,0 +1,64 @@
+# TypeProf 0.21.11
+
+module Kettle
+  module Dev
+    # CLI for updating CHANGELOG.md with new version sections
+    class ChangelogCLI
+      UNRELEASED_SECTION_HEADING: String
+
+      @root: String
+      @changelog_path: String
+      @coverage_path: String
+
+      def initialize: () -> void
+
+      # Main entry point that updates CHANGELOG.md
+      def run: () -> void
+
+      private
+
+      # Abort with error message
+      def abort: (String msg) -> void
+
+      # Detect version from lib/**/version.rb
+      def detect_version: () -> String
+
+      # Extract unreleased section from changelog
+      def extract_unreleased: (String content) -> [String?, String?, String?]
+
+      # Detect previous version from after text
+      def detect_previous_version: (String after_text) -> String?
+
+      # Filter unreleased sections keeping only those with content
+      def filter_unreleased_sections: (String unreleased_block) -> String
+
+      # Get coverage lines from coverage.json
+      def coverage_lines: () -> [String?, String?]
+
+      # Get YARD documentation percentage
+      def yard_percent_documented: () -> String?
+
+      # Convert legacy heading tag suffix to list format
+      def convert_heading_tag_suffix_to_list: (String text) -> String
+
+      # Update link references in changelog
+      def update_link_refs: (
+        String content,
+        String? owner,
+        String? repo,
+        String? prev_version,
+        String new_version
+      ) -> String
+
+      # Normalize spacing around headings
+      def normalize_heading_spacing: (String text) -> String
+
+      # Ensure proper footer spacing
+      def ensure_footer_spacing: (String text) -> String
+
+      # Detect initial compare base from changelog
+      def detect_initial_compare_base: (Array[String] lines) -> String
+    end
+  end
+end
+