kettle-dev 2.2.11 → 2.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adb949cc424b8cfc26b1a1d98557f027761ce0cf0335b27d11be8b2acc7492fb
-  data.tar.gz: e0b0f29328cb38c439d60997ef4d2162231c01b3dc086d5444d5e64124324e41
+  metadata.gz: 3f039cd2a52c5584b02f93a75f08e79227bbbc5e37f748a1d4a6623996fda1a8
+  data.tar.gz: 2ebc57a458091e9f531daafa63d431a1ac9f64f39d8fafb7e03fb802ac511e42
 SHA512:
-  metadata.gz: a300fc001ade1936c203f7be54b55da94706f3f70e536eaf24abeae941f1b9522d7a39d72bea83df2c918a6444a783c69c8c640d0c8ee69a3878e9b7b6496c9c
-  data.tar.gz: ea78dd32142a448c490631571ba4f42bdfa1171d62aa0d7fd414a3e38beae3785c3986b5ed1b6a4cd405f72250a7e8fcab89786e793cc1441e6f37c5c0856ca3
+  metadata.gz: dfc81acc32288dff4f6be9d4f84e31779017132a5eecd94f7881d3702ee0da968cb7687eb0ed6cdff31eceb321d30b29891bc2a43341aad6a877ddb93f9fe31f
+  data.tar.gz: 59440aa4a9abcbd46b861cb9e403e72d2cddd7dc1d4570423c99f5d82951571033fd22efe0f4b7ad774f3366a920345abb65f949656fba2b92b823a25aadacc2

data/CHANGELOG.md

@@ -30,6 +30,24 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.2.12] - 2026-06-18
+
+- TAG: [v2.2.12][2.2.12t]
+- COVERAGE: 92.52% -- 3947/4266 lines in 28 files
+- BRANCH COVERAGE: 74.11% -- 1569/2117 branches in 28 files
+- 63.76% documented
+
+### Added
+
+- Added `--version VERSION` support to `kettle-changelog` and `kettle-release`
+  for shim gems whose release version is intentionally sourced outside the local
+  `lib/**/version.rb` file.
+
+### Fixed
+
+- Updated `kettle-changelog` and `kettle-pre-release` help text to match current
+  coverage generation, documentation stats, and image URL cache behavior.
+
 ## [2.2.11] - 2026-06-17
 
 - TAG: [v2.2.11][2.2.11t]
@@ -2152,7 +2170,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.2.11...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.2.12...HEAD
+[2.2.12]: https://github.com/kettle-dev/kettle-dev/compare/v2.2.11...v2.2.12
+[2.2.12t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.2.12
 [2.2.11]: https://github.com/kettle-dev/kettle-dev/compare/v2.2.10...v2.2.11
 [2.2.11t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.2.11
 [2.2.10]: https://github.com/kettle-dev/kettle-dev/compare/v2.2.9...v2.2.10

data/README.md

@@ -854,7 +854,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.252-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.266-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-dev/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/exe/kettle-changelog

@@ -16,9 +16,13 @@
 #   GitLab links to GitHub links, and appends the new [X.Y.Z] and [X.Y.Zt] links.
 #
 # Notes:
-# - Expects a JSON coverage report at coverage/coverage.json. In strict mode,
-#   it will generate one with bundle exec kettle-test.
-# - Expects `bin/rake yard` to be available.
+# - 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
 
@@ -51,7 +55,7 @@ end
 begin
   if ARGV.include?("-h") || ARGV.include?("--help")
     puts <<~USAGE
-      Usage: kettle-changelog [--update-prep] [--pending-release] [--release-state] [--json] [--no-strict] [--no-coverage-threshold]
+      Usage: kettle-changelog [--version VERSION] [--update-prep] [--pending-release] [--release-state] [--json] [--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:
@@ -61,6 +65,7 @@ begin
       and update bottom link references to GitHub style.
 
       Options:
+        --version VERSION         Use this version instead of detecting VERSION from lib/**/version.rb
         --update-prep             Force updating the most recent prepared release section in place
         --pending-release         Query whether the changelog has release work pending; exits 0 for yes, 1 for no
         --release-state,
@@ -74,23 +79,50 @@ begin
         K_CHANGELOG_COVERAGE_HARD=false       Disable coverage threshold hard-failure
         K_CHANGELOG_VERSION_FILE=path         Read VERSION from this file instead of lib/**/version.rb
 
-      Prerequisites:
-        - coverage/coverage.json present (run: bundle exec kettle-test with K_SOUP_COV_FORMATTERS=json to generate)
-        - yard task available via bin/rake yard
+      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.
 
-      By default (strict mode), if coverage.json or yard stats are missing, the script will:
-        1. Attempt to generate them by running bundle exec kettle-test and bin/rake yard
-        2. Fail with an error if generation fails or data is still unavailable
-        3. Fail if coverage is below the configured project thresholds
+        Strict mode fails if specs fail, coverage JSON is not produced, coverage
+        is below the configured project thresholds, or documentation stats cannot
+        be collected.
 
-      Use --no-strict or K_CHANGELOG_STRICT=false to allow missing data (backward compatible behavior).
-      Use --no-coverage-threshold or K_CHANGELOG_COVERAGE_HARD=false to bypass coverage threshold failures.
+        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
 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
+
   # 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")
@@ -99,8 +131,9 @@ begin
   json_output = ARGV.delete("--json")
   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)
 
-  cli = Kettle::Dev::ChangelogCLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep)
+  cli = Kettle::Dev::ChangelogCLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep, version: version_override)
   if release_state_query
     state = cli.release_state
     puts(json_output ? JSON.pretty_generate(state) : cli.release_state_table(state))

data/exe/kettle-pre-release

@@ -5,7 +5,8 @@
 
 # kettle-pre-release: Run pre-release checks to catch avoidable mistakes.
 # - Structured as a sequence of checks that can be resumed via check_num
-# - Checks GitHub Actions SHA pins and validates Markdown image links.
+# - Checks GitHub Actions SHA pins, normalizes Markdown image URLs, and
+#   validates Markdown image links with a global seven-day success cache.
 
 require "optparse"
 
@@ -47,7 +48,13 @@ parser = OptionParser.new do |opts|
     puts "Checks:"
     puts "  1) Validate GitHub Actions SHA pins"
     puts "  2) Normalize Markdown image URLs"
-    puts "  3) Validate Markdown image links (HTTP HEAD)"
+    puts "  3) Validate Markdown image links (cached HTTP HEAD, with GET fallback)"
+    puts
+    puts "Image URL cache:"
+    puts "  Successful image URL validations are cached globally for seven days."
+    puts "  KETTLE_IMAGE_URL_CACHE=/path/to/cache.json  Use a custom cache path"
+    puts "  KETTLE_IMAGE_URL_CACHE=false                Disable the image URL cache"
+    puts "  KETTLE_IMAGE_URL_CACHE_REFRESH=true         Ignore cached successes and refresh"
     exit(0)
   end
 end

data/exe/kettle-release

@@ -43,7 +43,7 @@ end
 # Do not guard with __FILE__ == $PROGRAM_NAME because binstubs use Kernel.load.
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: kettle-release [--local-ci] [start_step=<1-19>]
+    Usage: kettle-release [--version VERSION] [--local-ci] [start_step=<1-19>]
 
     Automates the release flow for a Ruby gem in the host project.
 
@@ -74,6 +74,7 @@ if ARGV.include?("-h") || ARGV.include?("--help")
 
     Options:
       start_step=<number>         # Begin at the numbered step above (e.g., 10 to resume at CI monitoring)
+      --version VERSION           # Use this version instead of detecting VERSION from lib/**/version.rb
       --local-ci                  # Sensitive release mode: run act locally, publish before any git push,
                                   # create the git tag locally, then push commits and tags after publish
 
@@ -96,12 +97,31 @@ if ARGV.include?("-h") || ARGV.include?("--help")
 end
 
 # Parse start_step=<n> from ARGV
+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
+
 local_ci = ARGV.include?("--local-ci")
 start_step_arg = ARGV.find { |a| a.start_with?("start_step=") }
 start_step = start_step_arg ? start_step_arg.split("=", 2)[1].to_i : 1
+version_override = extract_version_arg!(ARGV)
 
 begin
-  Kettle::Dev::ReleaseCLI.new(start_step: start_step, local_ci: local_ci).run
+  Kettle::Dev::ReleaseCLI.new(start_step: start_step, local_ci: local_ci, version: version_override).run
 rescue LoadError => e
   warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
   warn(Array(e.backtrace).join("\n")) if ENV["DEBUG"]

data/lib/kettle/dev/changelog_cli.rb

@@ -24,13 +24,15 @@ module Kettle
       # @param strict [Boolean] when true (default), require coverage and yard data; raise errors if unavailable
       # @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)
+      # @param version [String, nil] explicit version override for gems without a literal VERSION constant
+      def initialize(strict: true, enforce_coverage_thresholds: true, update_prep: false, version: nil, root: Kettle::Dev::CIHelpers.project_root)
         @root = 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
+        @version_override = Kettle::Dev::Versioning.normalize_explicit_version(version)
       end
 
       # Main entry point to update CHANGELOG.md
@@ -40,7 +42,7 @@ module Kettle
       #
       # @return [void]
       def run
-        version = Kettle::Dev::Versioning.detect_version(@root)
+        version = detect_version
         today = Time.now.strftime("%Y-%m-%d")
         owner, repo = Kettle::Dev::CIHelpers.repo_info
         unless owner && repo
@@ -299,7 +301,7 @@ module Kettle
 
       def confirm_plan!(plan)
         puts "kettle-changelog selected plan: #{plan_label(plan.fetch(:action))}"
-        puts "  version.rb: #{plan.fetch(:version)}"
+        puts "  #{version_source_label(plan)}: #{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"}"
@@ -311,6 +313,13 @@ module Kettle
         abort("Aborting: changelog plan was not confirmed.")
       end
 
+      def version_source_label(plan)
+        return "prepared release" if plan.fetch(:explicit, false)
+        return "version override" if @version_override
+
+        "version.rb"
+      end
+
       def plan_label(action)
         case action
         when :new_release
@@ -389,7 +398,7 @@ module Kettle
       end
 
       def detect_version
-        Kettle::Dev::Versioning.detect_version(@root)
+        Kettle::Dev::Versioning.detect_version(@root, override: @version_override)
       end
 
       def extract_unreleased(content)

data/lib/kettle/dev/pre_release_cli.rb

@@ -20,7 +20,7 @@ module Kettle
     # Checks:
     #   1) Ensure GitHub Actions workflow actions are pinned to current SHAs.
     #   2) Normalize Markdown image URLs using Addressable normalization.
-    #   3) Validate Markdown image links resolve via HTTP(S) HEAD.
+    #   3) Validate Markdown image links resolve via cached HTTP(S) HEAD/GET.
     #
     # Usage: Kettle::Dev::PreReleaseCLI.new(check_num: 1).run
     class PreReleaseCLI
@@ -352,10 +352,10 @@ module Kettle
         nil
       end
 
-      # Check 3: Validate Markdown image links by HTTP HEAD (no rescue for parse failures)
+      # Check 3: Validate Markdown image links by cached HTTP HEAD/GET.
       # @return [void]
       def check_markdown_images_http!
-        puts "[kettle-pre-release] Check 3: Validate Markdown image links (HTTP HEAD)"
+        puts "[kettle-pre-release] Check 3: Validate Markdown image links (cached HTTP HEAD, with GET fallback)"
         urls = Markdown.extract_image_urls_from_files
         puts "[kettle-pre-release] Found #{urls.size} unique image URL(s)."
         cache = image_url_cache

data/lib/kettle/dev/release_cli.rb

@@ -70,12 +70,13 @@ module Kettle
 
       public
 
-      def initialize(start_step: 1, local_ci: false)
+      def initialize(start_step: 1, local_ci: false, version: nil)
         @root = Kettle::Dev::CIHelpers.project_root
         @git = Kettle::Dev::GitAdapter.new
         @start_step = (start_step || 1).to_i
         @start_step = 1 if @start_step < 1
         @local_ci = !!local_ci
+        @version_override = Kettle::Dev::Versioning.normalize_explicit_version(version)
       end
 
       def run
@@ -671,7 +672,7 @@ module Kettle
       end
 
       def detect_version
-        Kettle::Dev::Versioning.detect_version(@root)
+        Kettle::Dev::Versioning.detect_version(@root, override: @version_override)
       end
 
       def detect_gem_name

data/lib/kettle/dev/version.rb

@@ -3,7 +3,7 @@
 module Kettle
   module Dev
     module Version
-      VERSION = "2.2.11"
+      VERSION = "2.2.12"
     end
     VERSION = Version::VERSION # Traditional Constant Location
   end

data/lib/kettle/dev/versioning.rb

@@ -10,8 +10,12 @@ module Kettle
       # or in K_CHANGELOG_VERSION_FILE when a monorepo/root changelog needs
       # to point at a representative package version file.
       # @param root [String] project root
+      # @param override [String, nil] explicit version supplied by caller
       # @return [String] version string
-      def detect_version(root)
+      def detect_version(root, override: nil)
+        explicit = normalize_explicit_version(override)
+        return explicit if explicit
+
         candidates = version_file_candidates(root)
         versions = candidates.map do |path|
           content = File.read(path)
@@ -25,6 +29,16 @@ module Kettle
         versions.first
       end
 
+      def normalize_explicit_version(value)
+        version = value.to_s.strip
+        return nil if version.empty?
+
+        Gem::Version.new(version)
+        version
+      rescue ArgumentError
+        abort!("Invalid version override: #{version.inspect}")
+      end
+
       def version_file_candidates(root)
         override = ENV.fetch("K_CHANGELOG_VERSION_FILE", "").to_s.strip
         unless override.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 2.2.11
+  version: 2.2.12
 platform: ruby
 authors:
 - Peter H. Boling
@@ -338,10 +338,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.2.11
-  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.2.11/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.2.12
+  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.2.12/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.2.11
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.2.12
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev