kettle-changelog 1.0.0

data/exe/kettle-changelog

@@ -0,0 +1,244 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+# kettle-changelog: Generate a CHANGELOG.md entry for the current VERSION.
+# - Reads VERSION from lib/**/version.rb (must be unique across files)
+# - Set K_CHANGELOG_PATH to read/write a changelog outside the current gem root
+# - Set K_CHANGELOG_COVERAGE_ROOT to collect coverage from another bundle root
+# - Set K_CHANGELOG_VERSION_FILE to use a specific version.rb for monorepo roots
+# - Set K_CHANGELOG_GEM_NAME to use a specific gem name for root changelogs
+# - Moves entries from the "Unreleased" section into a new versioned section
+# - Prepends 4 heading lines:
+#   - TAG
+#   - COVERAGE (line coverage)
+#   - BRANCH COVERAGE (branch coverage)
+#   - percent documented (parsed from `bin/rake yard` output)
+# - Updates bottom link references to GitHub style, converts any existing
+#   GitLab links to GitHub links, and appends the new [X.Y.Z] and [X.Y.Zt] links.
+#
+# Notes:
+# - Strict mode (default) removes stale coverage output, runs `bundle exec
+#   kettle-test` with JSON coverage enabled, and reads the freshly generated
+#   coverage/coverage.json.
+# - Non-strict mode reads existing coverage JSON when present and leaves
+#   unavailable coverage or documentation stats blank with a warning.
+# - Expects `bin/rake yard` or `bin/yard` to be available for documentation stats
+#   when strict mode is enabled.
+
+$stdout.sync = true
+
+# Do not rely on Bundler; allow running in repos that do not depend on kettle-dev
+# Ensure RubyGems is available for 'require' lookups
+begin
+  require "rubygems"
+rescue LoadError
+  # Older Rubies always have rubygems; continue anyway
+end
+
+script_basename = File.basename(__FILE__)
+repo_lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(repo_lib) if File.directory?(repo_lib) && !$LOAD_PATH.include?(repo_lib)
+
+begin
+  # Standard library
+  require "json"
+  require "time"
+  require "open3"
+  require "shellwords"
+
+  # This library
+  require "kettle/changelog"
+  require "kettle/ndjson"
+  require "kettle/dev/executable_version"
+  Kettle::Dev::ExecutableVersion.print_and_exit!(script_basename, ARGV, value_option: true)
+  machine_output = ARGV.any? { |arg| arg == "--json" || arg.start_with?("--events") }
+  Kettle::Dev::ExecutableVersion.print_header(script_basename) unless machine_output
+rescue LoadError => e
+  warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+  warn("Hint: Ensure the host project has kettle-dev as a dependency and run bundle install.")
+  exit(1)
+end
+
+if ARGV.include?("-h") || ARGV.include?("--help")
+  puts <<~USAGE
+    Usage: kettle-changelog [--version VERSION] [--yes] [--update-prep|--reformat|--backfill-released-version VERSION] [--pending-release] [--release-state] [--refresh-cache] [--add-unreleased-entry --section SECTION --entry TEXT] [--json|--events[=TYPES]] [--no-strict] [--no-coverage-threshold]
+
+    Detects the current version from lib/**/version.rb, the latest live release, and
+    the most recent CHANGELOG.md release section, then prompts to confirm the selected plan:
+    create a new release section, update the prepared release section in place, or reformat only.
+
+    Release plans add coverage and documentation stats, move entries from [Unreleased],
+    and update bottom link references to GitHub style.
+
+    Options:
+      --version VERSION         Use this version instead of detecting VERSION from lib/**/version.rb
+      --yes                     Auto-approve the selected release plan
+      --update-prep             Force updating the most recent prepared release section in place
+      --reformat                Normalize CHANGELOG.md structure without release-state planning
+      --backfill-released-version VERSION
+                                Add a tagged historical section without moving Unreleased entries
+      --pending-release         Query whether the changelog has release work pending; exits 0 for yes, 1 for no
+      --release-state,
+      --release-status          Print changelog release state, including latest published release and pending sources
+      --refresh-cache           Bypass cached gem.coop version data for this invocation
+      --add-unreleased-entry    Add one entry to an existing section under ## [Unreleased]
+      --section SECTION         Unreleased section to receive the entry (Added, Changed, Deprecated, Removed, Fixed, Security)
+      --entry TEXT              Changelog entry text; "- " is added when omitted
+      --json                    Print query output as JSON
+      --events[=TYPES]          Print newline-delimited JSON changelog events
+      --no-strict               Allow missing coverage and yard data (warnings only, no errors)
+      --no-coverage-threshold   Generate coverage without hard-failing below configured thresholds
+
+    Environment:
+      K_CHANGELOG_STRICT=false              Disable strict mode (equivalent to --no-strict flag)
+      K_CHANGELOG_COVERAGE_HARD=false       Disable coverage threshold hard-failure
+      K_CHANGELOG_PATH=path                 Read and write this changelog instead of ./CHANGELOG.md
+      K_CHANGELOG_COVERAGE_ROOT=path        Run/read coverage from this root instead of the gem root
+      K_CHANGELOG_VERSION_FILE=path         Read VERSION from this file instead of lib/**/version.rb
+      K_CHANGELOG_GEM_NAME=name             Read live release data as this gem instead of root .gemspec
+      KETTLE_GEM_COOP_REFRESH=true          Bypass cached gem.coop version data
+
+    Data generation:
+      Strict mode is the default. Release plans remove stale coverage output,
+      run bundle exec kettle-test with JSON coverage enabled, read the resulting
+      coverage/coverage.json, and collect documentation stats from bin/rake yard
+      or bin/yard.
+
+      Strict mode fails if specs fail, coverage JSON is not produced, coverage
+      is below the configured project thresholds, or documentation stats cannot
+      be collected.
+
+      Non-strict mode does not generate missing coverage or documentation data;
+      it warns and leaves unavailable stats blank.
+
+    Runtime requirements:
+      - bundle exec kettle-test available for strict coverage generation
+      - bin/rake yard or bin/yard available for strict documentation stats
+
+    Use --no-strict or K_CHANGELOG_STRICT=false to allow missing data.
+    Use --no-coverage-threshold or K_CHANGELOG_COVERAGE_HARD=false to run fresh
+    coverage without hard-failing below configured thresholds.
+  USAGE
+  exit(0)
+end
+
+begin
+  def extract_version_arg!(argv)
+    version = nil
+    if (idx = argv.index("--version"))
+      version = argv[idx + 1]
+      Kettle::Dev::ExitAdapter.abort("--version requires a VERSION") if version.to_s.empty?
+      argv.slice!(idx, 2)
+    end
+    argv.delete_if do |arg|
+      if arg.start_with?("--version=", "version=")
+        version = arg.split("=", 2)[1]
+        true
+      else
+        false
+      end
+    end
+    Kettle::Dev::Versioning.normalize_explicit_version(version)
+  end
+
+  def extract_events_arg!(argv)
+    events = false
+    event_types = nil
+    argv.delete_if do |arg|
+      if arg == "--events"
+        events = true
+      elsif arg.start_with?("--events=")
+        events = true
+        event_types = arg.split("=", 2)[1]
+      else
+        false
+      end
+    end
+    [events, event_types]
+  end
+
+  # Determine if strict mode is enabled (default: true)
+  strict_mode = !ARGV.include?("--no-strict") && ENV.fetch("K_CHANGELOG_STRICT", "true").downcase != "false"
+  update_prep = ARGV.delete("--update-prep")
+  reformat_only = ARGV.delete("--reformat")
+  yes = !!ARGV.delete("--yes")
+  pending_release_query = ARGV.delete("--pending-release")
+  release_state_query = ARGV.delete("--release-state") || ARGV.delete("--release-status")
+  refresh_cache = ARGV.delete("--refresh-cache")
+  add_unreleased_entry = ARGV.delete("--add-unreleased-entry") || ARGV.delete("--add-changelog-entry")
+  json_output = ARGV.delete("--json")
+  events_output, event_types = extract_events_arg!(ARGV)
+  Kettle::Dev::ExitAdapter.abort("--events cannot be combined with --json") if events_output && json_output
+  coverage_threshold_disabled = ARGV.include?("--no-coverage-threshold") || ARGV.include?("--no-coverage-thresholds")
+  coverage_hard = !coverage_threshold_disabled && ENV.fetch("K_CHANGELOG_COVERAGE_HARD", "true").downcase != "false"
+  version_override = extract_version_arg!(ARGV)
+
+  def extract_option_arg!(argv, name)
+    value = nil
+    if (idx = argv.index(name))
+      value = argv[idx + 1]
+      Kettle::Dev::ExitAdapter.abort("#{name} requires a value") if value.to_s.empty?
+      argv.slice!(idx, 2)
+    end
+    argv.delete_if do |arg|
+      if arg.start_with?("#{name}=")
+        value = arg.split("=", 2)[1]
+        true
+      else
+        false
+      end
+    end
+    value
+  end
+
+  historical_backfill_version = extract_option_arg!(ARGV, "--backfill-released-version")
+
+  if add_unreleased_entry
+    section = extract_option_arg!(ARGV, "--section")
+    entry = extract_option_arg!(ARGV, "--entry")
+    Kettle::Dev::ExitAdapter.abort("--section is required with --add-unreleased-entry") if section.to_s.empty?
+    Kettle::Dev::ExitAdapter.abort("--entry is required with --add-unreleased-entry") if entry.to_s.empty?
+
+    result = Kettle::Changelog::EntryAdder.new(section: section, entry: entry).run
+    message = (result == :changed) ? "CHANGELOG.md updated under Unreleased #{section}." : "CHANGELOG.md already contains that Unreleased #{section} entry."
+    puts(json_output ? JSON.pretty_generate({changed: result == :changed, section: section, entry: entry}) : message)
+    exit(0)
+  end
+
+  event_stream = events_output ? Kettle::Ndjson.event_stream($stdout, types: event_types) : nil
+  cli = Kettle::Changelog::CLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep, reformat_only: reformat_only, historical_backfill_version: historical_backfill_version, version: version_override, refresh_cache: refresh_cache, yes: yes, event_stream: event_stream)
+  if release_state_query
+    state = cli.release_state
+    puts(json_output ? JSON.pretty_generate(state) : cli.release_state_table(state))
+    exit(0)
+  end
+
+  if pending_release_query
+    state = cli.pending_release_status
+    output = if json_output
+      JSON.pretty_generate(state)
+    elsif state.fetch(:pending_release)
+      "true"
+    else
+      "false"
+    end
+    puts(output)
+    exit(state.fetch(:pending_release) ? 0 : 1)
+  end
+
+  cli.run
+rescue LoadError => e
+  warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n")) if ENV["DEBUG"]
+  exit(1)
+rescue SystemExit => e
+  # Preserve exit status, but ensure at least a newline so shells don't show an empty line only.
+  warn("#{script_basename}: exited (status=#{e.status}, msg=#{e.message})") if e.status != 0
+  raise
+rescue => e
+  warn("#{script_basename}: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n"))
+  exit(1)
+end