kettle-dev 2.0.0 → 2.0.2

data/lib/kettle/dev/changelog_cli.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require "open3"
+require "json"
+require "net/http"
+require "uri"
+require "fileutils"
 
 module Kettle
   module Dev
@@ -10,15 +14,23 @@ module Kettle
     # includes coverage and YARD stats, and updates link references.
     class ChangelogCLI
       UNRELEASED_SECTION_HEADING = "[Unreleased]:"
+      # Matches a Markdown link-reference definition line, e.g. `[key]: https://...`
+      LINK_REF_DEF_RE = /^\s*\[[^\]]+\]:\s+\S+/
+      # Matches an ATX heading at H4 or deeper (####, #####, ...)
+      DEEP_HEADING_RE = /^[#]{4,}\s/
 
       # Initialize the changelog CLI
       # Sets up paths for CHANGELOG.md and coverage.json
       # @param strict [Boolean] when true (default), require coverage and yard data; raise errors if unavailable
-      def initialize(strict: true)
+      # @param enforce_coverage_thresholds [Boolean] when true, fail strict coverage generation below project thresholds
+      # @param update_prep [Boolean] when true, update the most recent prepared release section in place
+      def initialize(strict: true, enforce_coverage_thresholds: true, update_prep: false)
         @root = Kettle::Dev::CIHelpers.project_root
         @changelog_path = File.join(@root, "CHANGELOG.md")
         @coverage_path = File.join(@root, "coverage", "coverage.json")
         @strict = strict
+        @enforce_coverage_thresholds = enforce_coverage_thresholds
+        @update_prep = update_prep
       end
 
       # Main entry point to update CHANGELOG.md
@@ -36,28 +48,21 @@ module Kettle
           warn("Make sure 'origin' points to github.com. Alternatively, set origin or update links manually afterward.")
         end
 
+        changelog = File.read(@changelog_path)
+        plan = @update_prep ? explicit_update_prep_plan(changelog) : detect_plan(changelog, version)
+        confirm_plan!(plan)
+
+        if plan.fetch(:action) == :reformat_only
+          reformat_changelog!(changelog)
+          return
+        end
+
         line_cov_line, branch_cov_line = coverage_lines
         yard_line = yard_percent_documented
 
-        changelog = File.read(@changelog_path)
-
-        # If the detected version already exists in the changelog, offer reformat-only mode
-        if changelog =~ /^## \[#{Regexp.escape(version)}\]/
-          warn("CHANGELOG.md already has a section for version #{version}.")
-          warn("It appears the version has not been bumped. You can reformat CHANGELOG.md without adding a new release section.")
-          print("Proceed with reformat only? [y/N]: ")
-          ans = Kettle::Dev::InputAdapter.gets&.strip&.downcase
-          if ans == "y" || ans == "yes"
-            updated = convert_heading_tag_suffix_to_list(changelog)
-            updated = normalize_heading_spacing(updated)
-            updated = ensure_footer_spacing(updated)
-            updated = updated.rstrip + "\n"
-            File.write(@changelog_path, updated)
-            puts "CHANGELOG.md reformatted. No new version section added."
-            return
-          else
-            abort("Aborting: version not bumped. Re-run after bumping version or answer 'y' to reformat-only.")
-          end
+        if plan.fetch(:action) == :update_prepared_release
+          update_prepared_release!(changelog, today, owner, repo, line_cov_line, branch_cov_line, yard_line)
+          return
         end
 
         unreleased_block, before, after = extract_unreleased(changelog)
@@ -136,6 +141,160 @@ module Kettle
         Kettle::Dev::ExitAdapter.abort(msg)
       end
 
+      def detect_plan(changelog, version)
+        latest_overall = nil
+        latest_for_series = nil
+        gem_name = nil
+        begin
+          gem_name = detect_gem_name
+          latest_overall, latest_for_series = latest_released_versions(gem_name, version)
+        rescue StandardError => e
+          warn("[kettle-changelog] gem.coop release check failed: #{e.class}: #{e.message}")
+          warn("Proceeding without live release info.")
+        end
+
+        _unreleased_block, _before, after = extract_unreleased(changelog)
+        latest_changelog_version = detect_previous_version(after.to_s)
+        section_exists = release_section_exists?(changelog, version)
+        latest_target = latest_release_target(version, latest_overall, latest_for_series)
+
+        if latest_target && Gem::Version.new(version) < Gem::Version.new(latest_target)
+          abort("Aborting: version.rb (#{version}) is lower than the latest released version for this release line (#{latest_target}).")
+        end
+
+        if section_exists && latest_changelog_version != version
+          abort("Aborting: CHANGELOG.md already contains a #{version} section, but the most recent release section is #{latest_changelog_version || "missing"}.")
+        end
+
+        action = if section_exists && latest_target == version
+          :reformat_only
+        elsif section_exists
+          :update_prepared_release
+        elsif latest_target == version
+          abort("Aborting: version.rb (#{version}) matches the latest released version, but CHANGELOG.md does not have #{version} as the most recent release section.")
+        else
+          :new_release
+        end
+
+        {
+          action: action,
+          version: version,
+          gem_name: gem_name,
+          latest_overall: latest_overall,
+          latest_for_series: latest_for_series,
+          latest_target: latest_target,
+          latest_changelog_version: latest_changelog_version,
+        }
+      end
+
+      def explicit_update_prep_plan(changelog)
+        _unreleased_block, _before, after = extract_unreleased(changelog)
+        prepared_version = detect_previous_version(after.to_s)
+        abort("Could not find a prepared release section after '## [Unreleased]' in CHANGELOG.md") unless prepared_version
+
+        {
+          action: :update_prepared_release,
+          version: prepared_version,
+          gem_name: nil,
+          latest_overall: nil,
+          latest_for_series: nil,
+          latest_target: nil,
+          latest_changelog_version: prepared_version,
+          explicit: true,
+        }
+      end
+
+      def confirm_plan!(plan)
+        puts "kettle-changelog selected plan: #{plan_label(plan.fetch(:action))}"
+        puts "  version.rb: #{plan.fetch(:version)}"
+        puts "  latest released: #{plan.fetch(:latest_overall) || "unknown"}"
+        puts "  latest released for current series: #{plan.fetch(:latest_for_series) || "unknown"}"
+        puts "  latest CHANGELOG.md release: #{plan.fetch(:latest_changelog_version) || "none"}"
+        puts "  gem: #{plan.fetch(:gem_name) || "unknown"}"
+        print("Continue with this plan? [y/N]: ")
+        ans = Kettle::Dev::InputAdapter.gets&.strip&.downcase
+        return if ans == "y" || ans == "yes"
+
+        abort("Aborting: changelog plan was not confirmed.")
+      end
+
+      def plan_label(action)
+        case action
+        when :new_release
+          "create a new release section"
+        when :update_prepared_release
+          "update the prepared release section in place"
+        when :reformat_only
+          "reformat CHANGELOG.md without adding a release section"
+        else
+          action.to_s
+        end
+      end
+
+      def reformat_changelog!(changelog)
+        updated = convert_heading_tag_suffix_to_list(changelog)
+        updated = normalize_heading_spacing(updated)
+        updated = ensure_footer_spacing(updated)
+        updated = updated.rstrip + "\n"
+        File.write(@changelog_path, updated)
+        puts "CHANGELOG.md reformatted. No new version section added."
+      end
+
+      def release_section_exists?(changelog, version)
+        changelog.match?(/^## \[#{Regexp.escape(version)}\]/)
+      end
+
+      def detect_gem_name
+        gemspecs = Dir[File.join(@root, "*.gemspec")]
+        abort("Could not find a .gemspec in project root.") if gemspecs.empty?
+        path = gemspecs.min
+        content = File.read(path)
+        m = content.match(/spec\.name\s*=\s*(["'])([^"']+)\1/)
+        abort("Could not determine gem name from #{Kettle::Dev.display_path(path)}.") unless m
+
+        m[2]
+      end
+
+      def latest_released_versions(gem_name, current_version)
+        uri = URI("https://gem.coop/api/v1/versions/#{gem_name}.json")
+        res = Net::HTTP.get_response(uri)
+        return [nil, nil] unless res.is_a?(Net::HTTPSuccess)
+
+        data = JSON.parse(res.body)
+        versions = data.map { |h| h["number"] }.compact
+        versions.reject! { |v| v.to_s.include?("-pre") || v.to_s.include?(".pre") || v.to_s.match?(/[a-zA-Z]/) }
+        gversions = versions.map { |s| Gem::Version.new(s) }.sort
+        latest_overall = gversions.last&.to_s
+
+        cur = Gem::Version.new(current_version)
+        series = cur.segments[0, 2]
+        latest_series = gversions.reverse.find { |gv| gv.segments[0, 2] == series }&.to_s
+        [latest_overall, latest_series]
+      rescue StandardError => e
+        Kettle::Dev.debug_error(e, __method__)
+        [nil, nil]
+      end
+
+      def latest_release_target(version, latest_overall, latest_for_series)
+        return unless latest_overall
+
+        cur = Gem::Version.new(version)
+        overall = Gem::Version.new(latest_overall)
+        cur_series = cur.segments[0, 2]
+        overall_series = overall.segments[0, 2]
+
+        if latest_for_series
+          lfs_series = Gem::Version.new(latest_for_series).segments[0, 2]
+          latest_for_series = nil unless lfs_series == cur_series
+        end
+
+        if (cur_series <=> overall_series) == -1
+          latest_for_series
+        else
+          latest_overall
+        end
+      end
+
       def detect_version
         candidates = Dir[File.join(@root, "lib", "**", "version.rb")]
         abort("Could not find version.rb under lib/**.") if candidates.empty?
@@ -163,8 +322,23 @@ module Kettle
         end
         # Now next_i points to the next section heading or EOF
         before = lines[0..(start_i - 1)].join
-        unreleased_block = lines[(start_i + 1)..(next_i - 1)].join
-        after = lines[next_i..-1]&.join || ""
+        unreleased_body = lines[(start_i + 1)..(next_i - 1)] || []
+        after_lines = lines[next_i..-1] || []
+
+        # When this is the very first release there is no `## [X.Y.Z]` heading to act
+        # as a boundary, so the footer link-ref block ([Unreleased]: ...) sits at the
+        # end of the unreleased body.  Move everything from the [Unreleased]: line
+        # onward into `after` so those refs are not mistaken for section content.
+        if next_i == lines.length
+          footer_i = unreleased_body.index { |l| l.start_with?(UNRELEASED_SECTION_HEADING) }
+          if footer_i
+            after_lines = unreleased_body[footer_i..-1] + after_lines
+            unreleased_body = unreleased_body[0...footer_i]
+          end
+        end
+
+        unreleased_block = unreleased_body.join
+        after = after_lines.join
         [unreleased_block, before, after]
       end
 
@@ -176,6 +350,116 @@ module Kettle
         nil
       end
 
+      def update_prepared_release!(changelog, today, owner, repo, line_cov_line, branch_cov_line, yard_line)
+        unreleased_block, before, after = extract_unreleased(changelog)
+        abort("Could not find '## [Unreleased]' section in CHANGELOG.md") if unreleased_block.nil?
+
+        release_heading = after.to_s.match(/\A## \[(\d+\.\d+\.\d+)\][^\n]*\n/)
+        abort("Could not find a prepared release section after '## [Unreleased]' in CHANGELOG.md") unless release_heading
+
+        prepared_version = release_heading[1]
+        release_and_tail = after.lines
+        next_release_index = release_and_tail[1..-1].to_a.index { |line| line.start_with?("## [") }
+        release_line_count = next_release_index ? next_release_index + 1 : release_and_tail.length
+        release_lines = release_and_tail[0...release_line_count]
+        tail = release_and_tail[release_line_count..-1].to_a.join
+
+        release_body = release_lines[1..-1].to_a.join
+        merged_body = merge_release_body_with_unreleased(release_body, unreleased_block)
+
+        release_section = +""
+        release_section << "## [#{prepared_version}] - #{today}\n"
+        release_section << "- TAG: [v#{prepared_version}][#{prepared_version}t]\n"
+        release_section << "- #{line_cov_line}\n" if line_cov_line
+        release_section << "- #{branch_cov_line}\n" if branch_cov_line
+        release_section << "- #{yard_line}\n" if yard_line
+        release_section << merged_body
+        release_section.rstrip!
+        release_section << "\n\n"
+
+        unreleased_reset = <<~MD
+          ## [Unreleased]
+          ### Added
+          ### Changed
+          ### Deprecated
+          ### Removed
+          ### Fixed
+          ### Security
+        MD
+
+        previous_version = detect_previous_version(tail)
+        updated = before + unreleased_reset + "\n" + release_section + tail
+        updated = update_link_refs(updated, owner, repo, previous_version, prepared_version)
+        updated = convert_heading_tag_suffix_to_list(updated)
+        updated = normalize_heading_spacing(updated)
+        updated = updated.rstrip + "\n"
+
+        File.write(@changelog_path, updated)
+        puts "CHANGELOG.md updated in place for v#{prepared_version}."
+      end
+
+      def merge_release_body_with_unreleased(release_body, unreleased_block)
+        existing = strip_release_metadata(release_body)
+        incoming = filter_unreleased_sections(unreleased_block)
+        return existing if incoming.strip.empty?
+        return incoming if existing.strip.empty?
+
+        leading, sections = split_h3_sections(existing)
+        _incoming_leading, incoming_sections = split_h3_sections(incoming)
+        return [existing.rstrip, incoming.rstrip, ""].join("\n\n") if sections.empty? || incoming_sections.empty?
+
+        incoming_sections.each do |incoming_section|
+          section = sections.find { |candidate| candidate.fetch(:heading) == incoming_section.fetch(:heading) }
+          if section
+            section.fetch(:lines) << "\n" unless section.fetch(:lines).empty? || section.fetch(:lines).last.to_s.strip.empty?
+            section.fetch(:lines).concat(trim_blank_lines(incoming_section.fetch(:lines)))
+          else
+            sections << incoming_section
+          end
+        end
+
+        ([leading] + sections.map { |section| section.fetch(:heading) + trim_blank_lines(section.fetch(:lines)).join }).join.rstrip + "\n"
+      end
+
+      def strip_release_metadata(release_body)
+        lines = release_body.lines
+        while lines.any? && lines.first.strip.empty?
+          lines.shift
+        end
+        while lines.any?
+          stripped = lines.first.strip
+          break unless stripped.start_with?("- TAG:", "- COVERAGE:", "- BRANCH COVERAGE:") || stripped.match?(/\A- \d+(?:\.\d+)?%\s+documented\z/)
+
+          lines.shift
+        end
+        lines.join
+      end
+
+      def split_h3_sections(text)
+        leading = +""
+        sections = []
+        current = nil
+        text.lines.each do |line|
+          if line.start_with?("### ")
+            current = {heading: line, lines: []}
+            sections << current
+          elsif current
+            current.fetch(:lines) << line
+          else
+            leading << line
+          end
+        end
+        [leading, sections]
+      end
+
+      def trim_blank_lines(lines)
+        trimmed = lines.dup
+        trimmed.shift while trimmed.any? && trimmed.first.to_s.strip.empty?
+        trimmed.pop while trimmed.any? && trimmed.last.to_s.strip.empty?
+        trimmed << "\n" if trimmed.any? && !trimmed.last.end_with?("\n")
+        trimmed
+      end
+
       # From the Unreleased block, keep only sections that have content.
       # We detect sections as lines starting with '### '. A section has content if there is at least
       # one non-empty, non-heading line under it before the next '###' or '##'. Typically these are list items.
@@ -194,8 +478,10 @@ module Kettle
               chunk << lines[i]
               i += 1
             end
-            # Determine if chunk has any content (non-blank)
-            content_present = chunk.any? { |l| l.strip != "" }
+            # A section has real content only if it contains at least one non-blank line that is
+            # neither a link-reference definition ([key]: url) nor a deeper heading (H4+).
+            # Link-ref defs and H4+ headings alone are not meaningful section content.
+            content_present = chunk.any? { |l| l.strip != "" && l !~ LINK_REF_DEF_RE && l !~ DEEP_HEADING_RE }
             if content_present
               # Trim leading blank lines so there is no blank line after the header
               while chunk.any? && chunk.first.strip == ""
@@ -224,39 +510,28 @@ module Kettle
           # Delete old coverage files to ensure we get current data
           coverage_dir = File.dirname(@coverage_path)
           if Dir.exist?(coverage_dir)
-            puts "Cleaning old coverage data from #{coverage_dir}..."
+            puts "Cleaning old coverage data from #{Kettle::Dev.display_path(coverage_dir)}..."
             Dir.glob(File.join(coverage_dir, "*")).each do |file|
               File.delete(file) if File.file?(file)
             end
           end
 
-          puts "Generating fresh coverage data by running: bin/rake coverage"
-
-          # Run bin/rake coverage to generate coverage.json
-          rake_cmd = File.join(@root, "bin", "rake")
-          unless File.executable?(rake_cmd)
-            raise "bin/rake not found or not executable; cannot generate coverage data"
-          end
+          puts "Generating fresh coverage data by running: bundle exec kettle-test"
 
-          # Run the command exactly as the user would run it manually
-          # The coverage task knows how to configure itself properly
-          success = system(rake_cmd, "coverage", chdir: @root)
+          success = system(changelog_coverage_env, "bundle", "exec", "kettle-test", chdir: @root)
 
           unless success
-            raise "bin/rake coverage failed with exit status #{$?.exitstatus || "unknown"}"
+            raise "bundle exec kettle-test failed with exit status #{$?.exitstatus || "unknown"}"
           end
 
           puts "Coverage generation complete."
 
-          # Check if coverage.json was generated
-          unless File.file?(@coverage_path)
-            raise "Coverage JSON not found at #{@coverage_path} after running bin/rake coverage"
-          end
+          ensure_changelog_coverage_json!
         else
           # Non-strict mode: check if coverage.json exists, warn if not
           unless File.file?(@coverage_path)
-            warn("Coverage JSON not found at #{@coverage_path}.")
-            warn("Run: bin/rake coverage to generate it")
+            warn(coverage_json_missing_message)
+            warn("Run: K_SOUP_COV_FORMATTERS=json bundle exec kettle-test to generate it")
             return [nil, nil]
           end
         end
@@ -310,41 +585,100 @@ module Kettle
         end
       end
 
+      def changelog_coverage_env
+        {
+          "K_SOUP_COV_DO" => "true",
+          "K_SOUP_COV_FORMATTERS" => "json",
+          "K_SOUP_COV_MIN_HARD" => @enforce_coverage_thresholds ? "true" : "false",
+          "K_SOUP_COV_MULTI_FORMATTERS" => "true",
+          "K_SOUP_COV_OPEN_BIN" => "",
+        }
+      end
+
+      def ensure_changelog_coverage_json!
+        return if File.file?(@coverage_path)
+
+        raise coverage_json_missing_message
+      end
+
+      def coverage_json_missing_message
+        [
+          "Coverage JSON not found at #{Kettle::Dev.display_path(@coverage_path)} after running bundle exec kettle-test.",
+          "kettle-test runs specs in parallel and is expected to collate parallel SimpleCov results into this canonical file.",
+          "If it is missing, coverage was not enabled in ENV config or the rake/task hooks did not load the coverage integration.",
+        ].join(" ")
+      end
+
       def yard_percent_documented
-        cmd = File.join(@root, "bin", "yard")
-        unless File.executable?(cmd)
+        commands = yard_documentation_commands
+        if commands.empty?
           if @strict
-            raise "bin/yard not found or not executable; ensure yard is installed via bundler"
+            raise "bin/rake and bin/yard not found or not executable; ensure rake and yard are installed via bundler"
           else
-            warn("bin/yard not found or not executable; ensure yard is installed via bundler")
+            warn("bin/rake and bin/yard not found or not executable; ensure rake and yard are installed via bundler")
             return
           end
         end
 
         begin
-          # Run bin/yard to get documentation percentage
-          out, _ = Open3.capture2(cmd, {chdir: @root})
-          # Look for a line containing e.g., "95.35% documented"
-          line = out.lines.find { |l| l =~ /\d+(?:\.\d+)?%\s+documented/ }
-
-          if line
-            line.strip
-          elsif @strict
-            raise "Could not find documented percentage in bin/yard output"
+          # Run the canonical docs task to get the documentation percentage.
+          out = +""
+          commands.each do |command|
+            prepare_yard_fence_tmp_files if command == [File.join(@root, "bin", "yard")]
+            output, _status = Open3.capture2(*command, {chdir: @root})
+            out << output
+            line = documented_percent_line(output)
+            return line if line
+          end
+
+          if @strict
+            raise "Could not find documented percentage in bin/rake yard output"
           else
-            warn("Could not find documented percentage in bin/yard output.")
+            warn("Could not find documented percentage in bin/rake yard output.")
             nil
           end
         rescue StandardError => e
           if @strict
-            raise "Failed to run bin/yard: #{e.class}: #{e.message}"
+            raise "Failed to run bin/rake yard: #{e.class}: #{e.message}"
           else
-            warn("Failed to run bin/yard: #{e.class}: #{e.message}")
+            warn("Failed to run bin/rake yard: #{e.class}: #{e.message}")
             nil
           end
         end
       end
 
+      def yard_documentation_commands
+        commands = []
+        rake = File.join(@root, "bin", "rake")
+        commands << [rake, "yard"] if File.executable?(rake)
+        yard = File.join(@root, "bin", "yard")
+        commands << [yard] if File.executable?(yard)
+        commands
+      end
+
+      def prepare_yard_fence_tmp_files
+        yardopts = File.join(@root, ".yardopts")
+        return unless File.file?(yardopts)
+        return unless File.read(yardopts).include?("tmp/yard-fence")
+
+        require "yard/fence"
+        outdir = File.join(@root, "tmp", "yard-fence")
+        FileUtils.rm_rf(outdir)
+        FileUtils.mkdir_p(outdir)
+        Dir.glob(File.join(@root, Yard::Fence::GLOB_PATTERN)).each do |src|
+          next unless File.file?(src)
+
+          content = File.read(src)
+          sanitized = Yard::Fence.sanitize_text(content)
+          File.write(File.join(outdir, File.basename(src)), sanitized)
+        end
+      end
+
+      def documented_percent_line(output)
+        line = output.lines.find { |l| /\d+(?:\.\d+)?%\s+documented/.match?(l) }
+        line&.strip
+      end
+
       # Transform legacy release headings that include a tag suffix, e.g.:
       #   "## [1.2.3] 2022-08-29 ([tag][1.2.3t])"
       # into a heading followed by a list item:
@@ -511,7 +845,7 @@ module Kettle
         end
 
         # Rebuild and sort the reference block so Unreleased is first, then newest to oldest versions, preserving everything above first_ref
-        ref_lines = lines[first_ref..-1].select { |l| l =~ /^\[[^\]]+\]:\s+http/ }
+        ref_lines = lines[first_ref..-1].select { |l| /^\[[^\]]+\]:\s+http/.match?(l) }
         # Deduplicate by key (text inside the square brackets)
         by_key = {}
         ref_lines.each do |l|
@@ -560,12 +894,12 @@ module Kettle
         fence_re = /^\s*```/
         heading_re = /^\s*#+\s+.+/
         lines.each_with_index do |ln, idx|
-          if ln =~ fence_re
+          if fence_re.match?(ln)
             in_fence = !in_fence
             out << ln
             next
           end
-          if !in_fence && ln =~ heading_re
+          if !in_fence && heading_re.match?(ln)
             # Ensure previous line is blank (unless start of file or already blank)
             prev_blank = out.empty? ? false : out.last.to_s.strip == ""
             out << "" unless out.empty? || prev_blank
@@ -607,16 +941,40 @@ module Kettle
         (head + tail).join("\n")
       end
 
-      def detect_initial_compare_base(lines)
-        # Fallback when prev_version is unknown: try to find the first compare base used historically
-        # e.g., for 1.0.0 it may be a commit SHA instead of a tag
-        ref = lines.find { |l| l =~ /^\[1\.0\.0\]:\s+https:\/\/github\.com\// }
-        if ref && (m = ref.match(%r{compare/([^\.]+)\.\.\.v\d+})).is_a?(MatchData)
-          m[1]
-        else
-          # Default to previous tag name if none found (unlikely to be correct, but better than empty)
-          "HEAD^"
-        end
+      # Determine the "from" side of the compare URL for the very first release.
+      #
+      # Priority:
+      #   1. KETTLE_CHANGELOG_INITIAL_SHA env var — explicit override, required for hard-forks
+      #      (e.g. turbo_tests2 which forked from an upstream commit SHA).
+      #   2. `git rev-list --max-parents=0 HEAD` — the root commit of this repository.
+      #      Correct for the overwhelming majority of new gems.
+      #   3. "HEAD^" — last-resort fallback when git is unavailable or the command fails.
+      #
+      # @param _lines [Array<String>] kept for API compatibility (no longer used)
+      # @return [String] the compare base: a commit SHA, tag, or fallback string
+      def detect_initial_compare_base(_lines = nil)
+        env_sha = ENV.fetch("KETTLE_CHANGELOG_INITIAL_SHA", nil)
+        return env_sha.strip if env_sha && !env_sha.strip.empty?
+
+        sha = git_root_commit
+        return sha if sha
+
+        warn(
+          "Could not determine initial git root commit; using HEAD^ as compare base. " \
+            "Set KETTLE_CHANGELOG_INITIAL_SHA to override.",
+        )
+        "HEAD^"
+      end
+
+      # Return the root commit SHA of the current repository, or nil on failure.
+      # Uses the generic GitAdapter#capture escape hatch so tests can stub it.
+      def git_root_commit
+        adapter = Kettle::Dev::GitAdapter.new
+        out, ok = adapter.capture(["rev-list", "--max-parents=0", "HEAD"])
+        sha = out.to_s.lines.last&.strip   # take last line in case of multiple root commits
+        (ok && sha && !sha.empty?) ? sha : nil
+      rescue StandardError
+        nil
       end
     end
   end