kettle-dev 1.1.22 → 1.1.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b89634c46364a2a909b390e0e137ac3d4e5d14413e5a81a042cad3bb00b80414
-  data.tar.gz: fb3dd1c44deac3c08615dc5d3311296fec200c609b7cb868715db2268b7fe845
+  metadata.gz: d04b8ab4f92685e809649cfa00e1272adb8b3da37ac68b24034259f7a7e7052b
+  data.tar.gz: ab03c72bf61c27941a1592c5e7bd47f0c4fc0211bc2d04280b809a6ba4d1d0b9
 SHA512:
-  metadata.gz: '0701922d64b114389df908b92d5b47941df21365632a81c3bbda289a4a4d64e8b80e66d7d7036fe99cb4e4e8ddef64fde9c1ac27e47000ac505a74c3bec93a09'
-  data.tar.gz: a50bbf782ab163a2a950f407232addeeab718104094ff9855e3757427b83772b29c11073432ad4740f3429304bac29ff06820775f9c8d3034ad1b51f20aed5a2
+  metadata.gz: 33c386f8d38cbf5c6b87f54a56d133cf7d29f5265c1dd2279a27825a3c149a9d23293bbf71e9e359de952f812d00481c603255d8d7f1512e27edc9f14bedeca6
+  data.tar.gz: 0e9766d1e8746e056d1faece88d7df6542122af64d9cc789229b7881badca3c28b31f18acdc4eb4fbc080ad583000d6e906541f81867dfb8181732e828609ae1

data/.github/.codecov.yml.example

@@ -0,0 +1,14 @@
+codecov:
+  bot: "autobolt"
+  max_report_age: 24
+  disable_default_path_fixes: no
+  require_ci_to_pass: yes
+  notify:
+    after_n_builds: 2
+    wait_for_ci: yes
+coverage:
+  status:
+    project:
+      default:
+        target: 100%
+        threshold: 1%

data/.github/workflows/current.yml

@@ -45,15 +45,14 @@ jobs:
             rubygems: latest
             bundler: latest
 
-          # truffleruby-24.1
-          #   (according to documentation: targets Ruby 3.3 compatibility)
-          #   (according to runtime: targets Ruby 3.2 compatibility)
-          - ruby: "truffleruby"
-            appraisal: "current"
-            exec_cmd: "rake test"
-            gemfile: "Appraisal.root"
-            rubygems: default
-            bundler: default
+# Turn back on once allow-failures is a feature of GHA.
+#          # truffleruby-24.1 (targets Ruby 3.3 compatibility)
+#          - ruby: "truffleruby"
+#            appraisal: "current"
+#            exec_cmd: "rake test"
+#            gemfile: "Appraisal.root"
+#            rubygems: default
+#            bundler: default
 
           # jruby-10.0 (targets Ruby 3.4 compatibility)
           - ruby: "jruby"

data/.github/workflows/current.yml.example

@@ -0,0 +1,89 @@
+# Targets the evergreen latest release of ruby, truffleruby, and jruby
+name: Current
+
+permissions:
+  contents: read
+
+env:
+  K_SOUP_COV_DO: false
+
+on:
+  push:
+    branches:
+      - 'main'
+      - '*-stable'
+    tags:
+      - '!*' # Do not execute on tags
+  pull_request:
+    branches:
+      - '*'
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+# Cancels all previous workflow runs for the same branch that have not yet completed.
+concurrency:
+  # The concurrency group contains the workflow name and the branch name.
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  test:
+    if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')"
+    name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }}
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }}
+    env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps
+      BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile
+    strategy:
+      matrix:
+        include:
+          # Ruby 3.4
+          - ruby: "ruby"
+            appraisal: "current"
+            exec_cmd: "rake test"
+            gemfile: "Appraisal.root"
+            rubygems: latest
+            bundler: latest
+
+          # truffleruby-24.1 (targets Ruby 3.3 compatibility)
+          - ruby: "truffleruby"
+            appraisal: "current"
+            exec_cmd: "rake test"
+            gemfile: "Appraisal.root"
+            rubygems: default
+            bundler: default
+
+          # jruby-10.0 (targets Ruby 3.4 compatibility)
+          - ruby: "jruby"
+            appraisal: "current"
+            exec_cmd: "rake test"
+            gemfile: "Appraisal.root"
+            rubygems: default
+            bundler: default
+
+    steps:
+      - name: Checkout
+        if: ${{ !(env.ACT && startsWith(matrix.ruby, 'jruby')) }}
+        uses: actions/checkout@v5
+
+      - name: Setup Ruby & RubyGems
+        if: ${{ !(env.ACT && startsWith(matrix.ruby, 'jruby')) }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          rubygems: ${{ matrix.rubygems }}
+          bundler: ${{ matrix.bundler }}
+          bundler-cache: false
+
+      # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root)
+      # We need to do this first to get appraisal installed.
+      # NOTE: This does not use the primary Gemfile at all.
+      - name: Install Root Appraisal
+        if: ${{ !(env.ACT && startsWith(matrix.ruby, 'jruby')) }}
+        run: bundle
+      - name: Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}
+        if: ${{ !(env.ACT && startsWith(matrix.ruby, 'jruby')) }}
+        run: bundle exec appraisal ${{ matrix.appraisal }} bundle
+      - name: Tests for ${{ matrix.ruby }}@${{ matrix.appraisal }} via ${{ matrix.exec_cmd }}
+        if: ${{ !(env.ACT && startsWith(matrix.ruby, 'jruby')) }}
+        run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }}

data/.junie/guidelines.md

@@ -12,7 +12,8 @@ This document captures project-specific knowledge to streamline setup, testing,
     - See .env.local.example for an example of what to put in .env.local.
     - See CONTRIBUTING.md for details on how to set up your local environment.
 - Ruby and Bundler
-  - Runtime supports very old Rubies (>= 1.9.2) but development tooling targets >= 2.3 because of CI/setup-ruby and dev dependencies.
+  - Runtime supports Ruby >= 1.9.2.
+  - Development tooling targets Ruby >= 2.3 (minimum supported by setup-ruby GHA).
   - Use a recent Ruby (>= 3.4 recommended) for fastest setup and to exercise modern coverage behavior.
   - Install dependencies via Bundler in project root:
     - bundle install
@@ -89,7 +90,7 @@ This document captures project-specific knowledge to streamline setup, testing,
   - Place new specs under spec/ mirroring lib/ structure where possible. Do not require "spec_helper" at the top of spec files, as it is automatically loaded by .rspec.
   - If your code relies on environment variables that drive activation (see "Activation env vars" below), prefer using rspec-stubbed_env:
     - it does not support stubbing with blocks, but it does automatically clean up after itself.
-    - outside the example:
+    - the below config is included in all spec scenarios by the kettle-test gem, so no need to do it again; it is here for reference:
       include_context 'with stubbed env'
     - in a before hook, or in an example:
       stub_env("FLOSS_FUNDING_MY_NS" => "Free-as-in-beer")
@@ -133,6 +134,7 @@ Notes
 - Coverage reports: NEVER review the HTML report. Use JSON (preferred), XML, LCOV, or RCOV. For this project, always run tests with K_SOUP_COV_FORMATTERS set to "json".
 - Do NOT modify .envrc in tasks; when running tests locally or in scripts, manually prefix each run, e.g.: K_SOUP_COV_FORMATTERS="json" bin/rspec
 - For all the kettle-soup-cover options, see .envrc and find the K_SOUP_COV_* env vars.
+- NEVER modify ENV variables in tests directly. Always use the stub_env macro from the rspec-stubbed_env gem (more details in the testing section above).
 
 Important documentation rules
 - Do NOT edit files under docs/ manually; they are generated by `bundle exec rake yard` as part of the default rake task.

data/.junie/guidelines.md.example

@@ -0,0 +1,141 @@
+Project: kettle-dev — Development Guidelines (for advanced contributors)
+
+This document captures project-specific knowledge to streamline setup, testing, and ongoing development.
+
+1. Build and configuration
+- ENV is controlled by `direnv`.
+  - Two files are loaded:
+    - .envrc — environment variables for local development, committed to source control
+    - .env.local — environment variables that are not committed to source control. These setting override .envrc.
+  - Run `direnv allow` after making changes to .envrc or .env.local.
+    - See .envrc for details.
+    - See .env.local.example for an example of what to put in .env.local.
+    - See CONTRIBUTING.md for details on how to set up your local environment.
+- Ruby and Bundler
+  - Runtime supports Ruby >= {K_D_MIN_RUBY}
+  - Development tooling targets Ruby >= {K_D_MIN_DEV_RUBY} (minimum supported by setup-ruby GHA).
+  - Use a recent Ruby (>= 3.4 recommended) for fastest setup and to exercise modern coverage behavior.
+  - Install dependencies via Bundler in project root:
+    - bundle install
+- Rake tasks (preferred entry points)
+  - The Rakefile wires common workflows. Useful targets:
+    - rake spec — run RSpec suite (also aliased via rake test)
+    - rake coverage — run specs with coverage locally and open a report (requires kettle-soup-cover)
+    - rake rubocop_gradual:autocorrect — RuboCop-LTS Gradual, with autocorrect as default task
+    - rake reek and rake reek:update — code smell checks and persisted snapshots in REEK
+    - rake yard — generate YARD docs for lib and selected extra files
+    - rake bundle:audit and rake bundle:audit:update — dependency vulnerability checks
+    - rake build / rake release — gem build/release helper tasks (Bundler + stone_checksums)
+  - The default rake target runs a curated set of tasks; this varies for CI vs local (see CI env var logic in Rakefile).
+    - Always run the default rake task prior commits, and after making changes to lib/ code, or *.md files, to allow the linter to autocorrect, and to generate updated documentation.
+- Coverage orchestration
+  - Coverage is controlled by kettle-soup-cover and .simplecov. Thresholds (line and branch) are enforced and can fail the process.
+  - Thresholds are primarily controlled by environment variables (see .simplecov and comments therein) typically loaded via direnv (.envrc) and CI workflow (.github/workflows/coverage.yml). When running only a test subset, thresholds may fail; see Testing below.
+- Gem signing (for releases)
+  - Signing is enabled unless SKIP_GEM_SIGNING is set. If enabled and certificates are present (certs/<USER>.pem), gem build will attempt to sign using ~/.ssh/gem-private_key.pem.
+  - See CONTRIBUTING.md for releasing details; use SKIP_GEM_SIGNING when building in environments without the private key.
+  - Important for local testing (to avoid hanging prompts): ALWAYS skip signing when building locally to test the packaging or install process. Without the private key password, the build will wait indefinitely at a signing prompt.
+    - One-off commands (recommended):
+      - SKIP_GEM_SIGNING=true gem build kettle-dev.gemspec
+      - SKIP_GEM_SIGNING=true bundle exec rake build
+      - SKIP_GEM_SIGNING=true bundle exec rake release  # only to test workflow; do not actually push
+    - direnv option (optional, not recommended globally): add `export SKIP_GEM_SIGNING=true` to your .env.local when you know you won’t be signing in this environment.
+    - Remove or unset SKIP_GEM_SIGNING when performing a real, signed release in the environment that has the private key.
+
+2. Testing
+- Framework and helpers
+  - RSpec 3.13 with custom spec/spec_helper.rb configuration:
+    - silent_stream: STDOUT is silenced by default for examples to keep logs clean.
+      - To explicitly test console output, tag the example or group with :check_output.
+    - Global state hygiene: Around each example, FlossFunding.namespaces and FlossFunding.silenced are snapshotted and restored to prevent cross-test pollution.
+    - DEBUG toggle: Set DEBUG=true to require 'debug' and avoid silencing output during your run.
+    - ENV seeding: The suite sets ENV["FLOSS_FUNDING_FLOSS_FUNDING"] = "Free-as-in-beer" so that the library’s own namespace is considered activated (avoids noisy warnings).
+    - Coverage: kettle-soup-cover integrates SimpleCov; .simplecov is invoked from spec_helper when enabled by Kettle::Soup::Cover::DO_COV, which is controlled by K_SOUP_COV_DO being set to true / false.
+    - RSpec.describe usage:
+      - Use `describe "#<method_name>"` to contain a block of specs that test instance method behavior.
+      - Use `describe "::<method_name>"` to contain a block of specs that test class method behavior.
+      - Do not use `describe ".<method_name>"` because the dot is ambiguous w.r.t instance vs. class methods.
+    - When adding new code or modifying existing code always add tests to cover the updated behavior, including branches, and different types of expected and unexpected inputs.
+  - Additional test utilities:
+    - rspec-stubbed_env: Use stub_env to control ENV safely within examples.
+    - timecop-rspec: Time manipulation is available, and is setup by kettle-test.
+      - To freeze time use `freeze: Time.new(*args)` tag on an example or group
+- Running tests (verified)
+  - Full suite (recommended to satisfy coverage thresholds):
+    - bin/rspec
+    - or: bundle exec rspec
+    - or: bundle exec rake spec
+  - Progress format (less verbose):
+    - bundle exec rspec --format progress
+  - Focused runs
+    - You can run a single file or example, but note: coverage thresholds need to be disabled with K_SOUP_COV_MIN_HARD=false
+    - Example: K_SOUP_COV_MIN_HARD=false bin/rspec spec/kettle-dev/class_spec.rb:42
+  - Output visibility
+    - To see STDOUT from the code under test, use the :check_output tag on the example or group.
+      Example:
+      RSpec.describe "output", :check_output do
+        it "prints" do
+          puts "This output should be visible"
+          expect(true).to be true
+        end
+      end
+    - Alternatively, run with DEBUG=true to disable silencing for the entire run.
+  - During a spec run, the presence of output about missing activation keys is often expected, since it is literally what this library is for. It only indicates a failure if the spec expected all activation keys to be present, and not all specs do.
+- Adding new tests (guidelines)
+  - Organize specs by class/module. Do not create per-task umbrella spec files; add examples to the existing spec for the class/module under test, or create a new spec file for that class/module if one does not exist. Only create a standalone scenario spec when it intentionally spans multiple classes for an integration/benchmark scenario (e.g., bench_integration_spec), and name it accordingly.
+  - Spec file names must map to a real class or module under lib/ (mirror the path). Do not introduce specs for non-existent classes or ad-hoc names (e.g., avoid template_helpers_replacements_spec.rb when testing Kettle::Dev::TemplateHelpers; add those examples to template_helpers_spec.rb).
+  - REQUIRED: Provide unit tests for every class, module, constant, and public method. Place them in spec/ mirroring the path under lib/. When a file under lib/ is added or changed, ensure a corresponding spec file exists/updated for it.
+  - Add tests for all public methods and add contexts for variations of their arguments, and arity.
+  - This repository targets near-100% coverage of its public API; when you add new public methods, rake tasks to a rakelib, or config behavior, add or update specs accordingly.
+  - Place new specs under spec/ mirroring lib/ structure where possible. Do not require "spec_helper" at the top of spec files, as it is automatically loaded by .rspec.
+  - If your code relies on environment variables that drive activation (see "Activation env vars" below), prefer using rspec-stubbed_env:
+    - it does not support stubbing with blocks, but it does automatically clean up after itself.
+    - the below config is included in all spec scenarios by the kettle-test gem, so no need to do it again; it is here for reference:
+      include_context 'with stubbed env'
+    - in a before hook, or in an example:
+      stub_env("FLOSS_FUNDING_MY_NS" => "Free-as-in-beer")
+      # example code continues
+  - If your spec needs to assert on console output, tag it with :check_output. By default, STDOUT is silenced.
+  - Use Timecop for deterministic time-sensitive behavior as needed (require config/timecop is already done by spec_helper).
+
+- Types and documentation
+  - REQUIRED: All public APIs must have RBS type signatures checked into sig/ under the corresponding path. When you add a new public method or change a signature, update the matching .rbs file.
+  - REQUIRED: All public methods must include inline YARD docs with @param/@return (and @yield/@option where applicable). Generate docs with `bundle exec rake yard` to verify formatting.
+
+3. Additional development information
+- Code style and static analysis
+  - RuboCop-LTS (Gradual) is integrated. Use:
+    - bundle exec rake rubocop_gradual:autocorrect
+    - bundle exec rake rubocop_gradual:force_update # only run if there are still linting violations the default rake task, which includes autocorrect locally, or a standalone autocorrect task, has run, and failed, and the violations won't be fixed
+  - Reek is configured to scan {lib,spec,tests}/**/*.rb. Use:
+    - bundle exec rake reek
+    - bundle exec rake reek:update              # writes current output to REEK, fails on smells
+    - Keep REEK file updated with intentional smells snapshot when appropriate (e.g., after refactors).
+    - Locally, the default rake task includes reek:update.
+- Documentation
+  - Generate YARD docs with: bundle exec rake yard. It includes lib/**/*.rb and extra docs like README.md, CHANGELOG.md, RUBOCOP.md, REEK, etc.
+- Appraisal and multi-gemfile testing
+  - appraisal2 is present to manage multiple dependency sets; see Appraisals and gemfiles/modular/*.gemfile. If you need to verify against alternate dependency versions, use Appraisal to install and run rspec under those Gemfiles.
+  - You can run a single github workflow by running `act -W /github/workflows/<workflow name>.yml`
+- CI/local differences and defaults
+  - The Rakefile adjusts default tasks based on CI env var. Locally, rake default may include coverage, reek:update, yard, etc. On CI, it tends to just run spec.
+
+Quick start
+1) bundle install
+2) K_SOUP_COV_FORMATTERS="json" bin/rspec (generates a JSON coverage report with both line and branch data in coverage/. Use this single format.)
+3) Static analysis: bundle exec rake rubocop_gradual:check && bundle exec rake reek
+
+Notes
+- ALWAYS Run bundle exec rake rubocop_gradual:autocorrect as the final step before completing a task, to lint and autocorrect any remaining issues. Then if there are new lint failures, attempt to correct them manually.
+- NEVER run vanilla rubocop, as it won't handle the linting config properly. Always run rubocop_gradual:autocorrect or rubocop_gradual.
+- Running only a subset of specs is supported but in order to bypass the hard failure due to coverage thresholds, you need to run with K_SOUP_COV_MIN_HARD=false.
+- When adding code that writes to STDOUT, remember most specs silence output unless tagged with :check_output or DEBUG=true.
+- Completion criteria after changes: Only consider your change “done” when the relevant examples pass, as verified by .rspec_status. Do not rely on STDOUT impressions; consult .rspec_status (and example IDs) to confirm green results for the affected files/examples. If you ran a subset, re-run the full suite before finalizing to restore coverage thresholds.
+- Coverage reports: NEVER review the HTML report. Use JSON (preferred), XML, LCOV, or RCOV. For this project, always run tests with K_SOUP_COV_FORMATTERS set to "json".
+- Do NOT modify .envrc in tasks; when running tests locally or in scripts, manually prefix each run, e.g.: K_SOUP_COV_FORMATTERS="json" bin/rspec
+- For all the kettle-soup-cover options, see .envrc and find the K_SOUP_COV_* env vars.
+- NEVER modify ENV variables in tests directly. Always use the stub_env macro from the rspec-stubbed_env gem (more details in the testing section above).
+
+Important documentation rules
+- Do NOT edit files under docs/ manually; they are generated by `bundle exec rake yard` as part of the default rake task.
+- Clarification: Executable scripts provided by this gem (exe/* and installed binstubs) work when the gem is installed as a system gem (gem install kettle-dev). However, the Rake tasks provided by this gem require kettle-dev to be declared as a development dependency in the host project's Gemfile and loaded in the project's Rakefile.

data/CHANGELOG.md

@@ -30,6 +30,38 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.1.24] - 2025-09-17
+
+- TAG: [v1.1.24][1.1.24t]
+- COVERAGE: 96.85% -- 3694/3814 lines in 26 files
+- BRANCH COVERAGE: 81.81% -- 1520/1858 branches in 26 files
+- 78.21% documented
+
+### Added
+
+- Replace template tokens with real minimum ruby versions for runtime and development
+
+### Changed
+
+- consolidated specs
+
+### Fixed
+
+- All .example files are now included in the gem package
+- Leaky state in specs
+
+## [1.1.23] - 2025-09-16
+
+- TAG: [v1.1.23][1.1.23t]
+- COVERAGE: 96.71% -- 3673/3798 lines in 26 files
+- BRANCH COVERAGE: 81.57% -- 1509/1850 branches in 26 files
+- 77.97% documented
+
+### Fixed
+
+- GemSpecReader, ReadmeBackers now use shared OpenCollectiveConfig
+  - fixes broken opencollective config handling in GemSPecReader
+
 ## [1.1.22] - 2025-09-16
 
 - TAG: [v1.1.22][1.1.22t]
@@ -937,7 +969,11 @@ 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-rb/kettle-dev/compare/v1.1.22...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.24...HEAD
+[1.1.24]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.23...v1.1.24
+[1.1.24t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.24
+[1.1.23]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.22...v1.1.23
+[1.1.23t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.23
 [1.1.22]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.21...v1.1.22
 [1.1.22t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.22
 [1.1.21]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.20...v1.1.21

data/README.md

@@ -916,7 +916,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-3.781-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.814-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: 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/README.md.example

@@ -41,7 +41,7 @@
 
 ### Compatibility
 
-Compatible with MRI Ruby 2.3+, and concordant releases of JRuby, and TruffleRuby.
+Compatible with MRI Ruby {K_D_MIN_RUBY}+, and concordant releases of JRuby, and TruffleRuby.
 
 | 🚚 _Amazing_ test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚             |
 |------------------------------------------------|--------------------------------------------------------|
@@ -513,7 +513,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-3.781-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.814-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: 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/Rakefile.example

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kettle-dev Rakefile v1.1.22 - 2025-09-16
+# kettle-dev Rakefile v1.1.24 - 2025-09-17
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/kettle-dev.gemspec.example

@@ -95,7 +95,7 @@ Gem::Specification.new do |spec|
   ]
   spec.require_paths = ["lib"]
   spec.bindir = "exe"
-  # files listed are relative paths from bindir above.
+  # Listed files are the relative paths from bindir above.
   spec.executables = []
 
   # Utilities
@@ -105,18 +105,17 @@ Gem::Specification.new do |spec|
   #       visibility and discoverability on RubyGems.org.
   #       However, development dependencies in gemspec will install on
   #       all versions of Ruby that will run in CI.
-  #       This gem, and its gemspec runtime dependencies, will install on Ruby down to 2.3.x.
-  #       This gem, and its gemspec development dependencies, will install on Ruby down to 2.3.x.
-  #       This is because in CI easy installation of Ruby, via setup-ruby, is for >= 2.3.
+  #       This gem, and its gemspec runtime dependencies, will install on Ruby down to {K_D_MIN_RUBY}.
+  #       This gem, and its gemspec development dependencies, will install on Ruby down to {K_D_MIN_DEV_RUBY}.
   #       Thus, dev dependencies in gemspec must have
   #
-  #       required_ruby_version ">= 2.3" (or lower)
+  #       required_ruby_version ">= {K_D_MIN_DEV_RUBY}" (or lower)
   #
   #       Development dependencies that require strictly newer Ruby versions should be in a "gemfile",
   #       and preferably a modular one (see gemfiles/modular/*.gemfile).
 
   # Dev, Test, & Release Tasks
-  spec.add_development_dependency("{KETTLE|DEV|GEM}", "~> 1.1")            # ruby >= 2.3.0
+  spec.add_development_dependency("{KETTLE|DEV|GEM}", "~> 1.1")                     # ruby >= 2.3.0
 
   # Security
   spec.add_development_dependency("bundler-audit", "~> 0.9.2")                      # ruby >= 2.0.0

data/lib/kettle/dev/gem_spec_reader.rb

@@ -97,40 +97,37 @@ module Kettle
           entrypoint_require = gem_name.to_s.tr("-", "/")
           gem_shield = gem_name.to_s.gsub("-", "--").gsub("_", "__")
 
-          # Funding org detection with bypass support.
-          # By default a funding org must be discoverable, unless explicitly disabled by ENV['FUNDING_ORG'] == 'false'.
-          funding_org_env = ENV["FUNDING_ORG"]
-          funding_org = funding_org_env.to_s.strip
+          # Funding org (Open Collective handle) detection.
+          # Precedence:
+          #   1) ENV["FUNDING_ORG"] when set:
+          #        - value "false" (any case) disables funding (nil)
+          #        - otherwise use the value verbatim
+          #   2) OpenCollectiveConfig.handle(required: false)
+          # Be lenient: allow nil when not discoverable, with a concise warning.
           begin
-            # Handle bypass: allow explicit string 'false' (any case) to disable funding org requirement.
-            if funding_org_env && funding_org_env.to_s.strip.casecmp("false").zero?
-              funding_org = nil
-            else
-              # Prefer .opencollective.yml when present so that specs forcing the file path are stable
-              oc_path = File.join(root.to_s, ".opencollective.yml")
-              if File.file?(oc_path)
-                txt = File.read(oc_path)
-                funding_org = if (m = txt.match(/\borg:\s*([\w\-]+)/i))
-                  m[1].to_s
-                else
-                  ""
-                end
+            env_funding = ENV["FUNDING_ORG"]
+            if env_funding && !env_funding.to_s.strip.empty?
+              funding_org = if env_funding.to_s.strip.casecmp("false").zero?
+                nil
+              else
+                env_funding.to_s
               end
+            else
+              # Preflight: if a YAML exists under the provided root, attempt to read it here so
+              # unexpected file IO errors surface within this rescue block (see specs).
+              oc_path = OpenCollectiveConfig.yaml_path(root)
+              File.read(oc_path) if File.file?(oc_path)
 
-              # Fallback to ENV when file not present or did not contain an org
+              funding_org = OpenCollectiveConfig.handle(required: false, root: root)
               if funding_org.to_s.strip.empty?
-                funding_org = ENV["OPENCOLLECTIVE_HANDLE"].to_s.strip if funding_org.empty?
-              end
-
-              # Be lenient: if funding_org cannot be determined, do not raise — leave it nil and warn.
-              if funding_org.to_s.empty?
-                Kernel.warn("kettle-dev: Could not determine funding org.\n  - Options:\n    * Set ENV['FUNDING_ORG'] to your funding handle (e.g., 'opencollective-handle').\n    * Or set ENV['OPENCOLLECTIVE_HANDLE'].\n    * Or add .opencollective.yml with: org: <handle>\n    * Or bypass by setting ENV['FUNDING_ORG']=false for gems without funding.")
+                Kernel.warn("kettle-dev: Could not determine funding org.\n  - Options:\n    * Set ENV['FUNDING_ORG'] to your funding handle, or 'false' to disable.\n    * Or set ENV['OPENCOLLECTIVE_HANDLE'].\n    * Or add .opencollective.yml with: collective: <handle> (or org: <handle>).\n    * Or proceed without funding if not applicable.")
                 funding_org = nil
               end
             end
           rescue StandardError => error
             Kettle::Dev.debug_error(error, __method__)
-            raise Error, "Unable to determine funding org from env or .opencollective.yml.\n\tError was: #{error.class}: #{error.message}"
+            # In an unexpected exception path, escalate to a domain error to aid callers/specs
+            raise Kettle::Dev::Error, "Unable to determine funding org: #{error.message}"
           end
 
           {

data/lib/kettle/dev/open_collective_config.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Kettle
+  module Dev
+    # Shared utility for resolving Open Collective configuration for this repository.
+    # Centralizes the logic for locating and reading .opencollective.yml and
+    # for deriving the handle from environment or the YAML file.
+    module OpenCollectiveConfig
+      module_function
+
+      # Absolute path to a .opencollective.yml
+      # @param root [String, nil] optional project root to resolve against; when nil, uses this repo root
+      # @return [String]
+      def yaml_path(root = nil)
+        return File.expand_path(".opencollective.yml", root) if root
+        File.expand_path("../../../.opencollective.yml", __dir__)
+      end
+
+      # Determine the Open Collective handle.
+      # Precedence:
+      #   1) ENV["OPENCOLLECTIVE_HANDLE"] when set and non-empty
+      #   2) .opencollective.yml key "collective" (or :collective)
+      #
+      # @param required [Boolean] when true, aborts the process if not found; when false, returns nil
+      # @param root [String, nil] optional project root to look for .opencollective.yml
+      # @return [String, nil] the handle, or nil when not required and not discoverable
+      def handle(required: false, root: nil, strict: false)
+        env = ENV["OPENCOLLECTIVE_HANDLE"]
+        return env unless env.nil? || env.to_s.strip.empty?
+
+        ypath = yaml_path(root)
+        if strict
+          yml = YAML.safe_load(File.read(ypath))
+          if yml.is_a?(Hash)
+            handle = yml["collective"] || yml[:collective] || yml["org"] || yml[:org]
+            return handle.to_s unless handle.nil? || handle.to_s.strip.empty?
+          end
+        elsif File.file?(ypath)
+          begin
+            yml = YAML.safe_load(File.read(ypath))
+            if yml.is_a?(Hash)
+              handle = yml["collective"] || yml[:collective] || yml["org"] || yml[:org]
+              return handle.to_s unless handle.nil? || handle.to_s.strip.empty?
+            end
+          rescue StandardError => e
+            Kettle::Dev.debug_error(e, __method__) if Kettle::Dev.respond_to?(:debug_error)
+            # fall through to required check
+          end
+        end
+
+        if required
+          Kettle::Dev::ExitAdapter.abort("ERROR: Open Collective handle not provided. Set OPENCOLLECTIVE_HANDLE or add 'collective: <handle>' to .opencollective.yml.")
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/kettle/dev/readme_backers.rb

@@ -20,9 +20,11 @@ module Kettle
 
       DEFAULT_AVATAR = "https://opencollective.com/static/images/default-avatar.png"
       README_PATH = File.expand_path("../../../README.md", __dir__)
-      OC_YML_PATH = File.expand_path("../../../.opencollective.yml", __dir__)
       README_OSC_TAG_DEFAULT = "OPENCOLLECTIVE"
       COMMIT_SUBJECT_DEFAULT = "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"
+      # Deprecated constant maintained for backwards compatibility in tests/specs.
+      # Prefer OpenCollectiveConfig.yaml_path going forward.
+      OC_YML_PATH = OpenCollectiveConfig.yaml_path
 
       # Ruby 2.3 compatibility: Struct keyword_init added in Ruby 2.5
       # Switch to struct when dropping ruby < 2.5
@@ -120,9 +122,9 @@ module Kettle
         env = ENV["KETTLE_DEV_BACKER_README_OSC_TAG"].to_s
         return env unless env.strip.empty?
 
-        if File.file?(OC_YML_PATH)
+        if File.file?(OpenCollectiveConfig.yaml_path)
           begin
-            yml = YAML.safe_load(File.read(OC_YML_PATH))
+            yml = YAML.safe_load(File.read(OpenCollectiveConfig.yaml_path))
             if yml.is_a?(Hash)
               from_yml = yml["readme-osc-tag"] || yml[:"readme-osc-tag"]
               from_yml = from_yml.to_s if from_yml
@@ -148,15 +150,7 @@ module Kettle
       end
 
       def resolve_handle
-        env = ENV["OPENCOLLECTIVE_HANDLE"]
-        return env unless env.nil? || env.strip.empty?
-
-        if File.file?(OC_YML_PATH)
-          yml = YAML.safe_load(File.read(OC_YML_PATH))
-          handle = yml.is_a?(Hash) ? yml["collective"] || yml[:collective] : nil
-          return handle.to_s unless handle.nil? || handle.to_s.strip.empty?
-        end
-        abort("ERROR: Open Collective handle not provided. Set OPENCOLLECTIVE_HANDLE or add 'collective: <handle>' to .opencollective.yml.")
+        OpenCollectiveConfig.handle(required: true)
       end
 
       def fetch_members(path)

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

@@ -150,6 +150,7 @@ module Kettle
                     namespace: namespace,
                     namespace_shield: namespace_shield,
                     gem_shield: gem_shield,
+                    min_ruby: min_ruby,
                   )
                 end
               else
@@ -162,6 +163,7 @@ module Kettle
                     namespace: namespace,
                     namespace_shield: namespace_shield,
                     gem_shield: gem_shield,
+                    min_ruby: min_ruby,
                   )
                 end
               end
@@ -259,6 +261,7 @@ module Kettle
                     namespace: namespace,
                     namespace_shield: namespace_shield,
                     gem_shield: gem_shield,
+                    min_ruby: min_ruby,
                   )
                 else
                   content.dup
@@ -469,6 +472,7 @@ module Kettle
                   namespace: namespace,
                   namespace_shield: namespace_shield,
                   gem_shield: gem_shield,
+                  min_ruby: min_ruby,
                 )
 
                 # 2) Merge specific sections from destination README, if present
@@ -618,6 +622,7 @@ module Kettle
                   namespace: namespace,
                   namespace_shield: namespace_shield,
                   gem_shield: gem_shield,
+                  min_ruby: min_ruby,
                 )
                 if File.basename(rel) == "CHANGELOG.md"
                   begin

data/lib/kettle/dev/template_helpers.rb

@@ -13,6 +13,8 @@ module Kettle
       @@template_results = {}
 
       EXECUTABLE_GIT_HOOKS_RE = %r{[\\/]\.git-hooks[\\/](commit-msg|prepare-commit-msg)\z}
+      # The minimum Ruby supported by setup-ruby GHA
+      MIN_SETUP_RUBY = Gem::Version.create("2.3")
 
       module_function
 
@@ -409,14 +411,56 @@ module Kettle
       # @param gem_shield [String]
       # @param funding_org [String, nil]
       # @return [String]
-      def apply_common_replacements(content, org:, gem_name:, namespace:, namespace_shield:, gem_shield:, funding_org: nil)
+      def apply_common_replacements(content, org:, gem_name:, namespace:, namespace_shield:, gem_shield:, funding_org: nil, min_ruby: nil)
         raise Error, "Org could not be derived" unless org && !org.empty?
         raise Error, "Gem name could not be derived" unless gem_name && !gem_name.empty?
 
         funding_org ||= org
+        # Derive min_ruby if not provided
+        mr = begin
+          meta = gemspec_metadata
+          meta[:min_ruby]
+        rescue StandardError => e
+          Kettle::Dev.debug_error(e, __method__)
+          # leave min_ruby as-is (possibly nil)
+        end
+        if min_ruby.nil? || min_ruby.to_s.strip.empty?
+          min_ruby = mr.respond_to?(:to_s) ? mr.to_s : mr
+        end
+
+        # Derive min_dev_ruby from min_ruby
+        # min_dev_ruby is the greater of min_dev_ruby and ruby 2.3,
+        #   because ruby 2.3 is the minimum ruby supported by setup-ruby GHA
+        min_dev_ruby = begin
+          [mr, MIN_SETUP_RUBY].max
+        rescue StandardError => e
+          Kettle::Dev.debug_error(e, __method__)
+          MIN_SETUP_RUBY
+        end
+
         c = content.dup
         c = c.gsub("kettle-rb", org.to_s)
         c = c.gsub("{OPENCOLLECTIVE|ORG_NAME}", funding_org)
+        # Replace min ruby token if present
+        begin
+          if min_ruby && !min_ruby.to_s.empty? && c.include?("{K_D_MIN_RUBY}")
+            c = c.gsub("{K_D_MIN_RUBY}", min_ruby.to_s)
+          end
+        rescue StandardError => e
+          Kettle::Dev.debug_error(e, __method__)
+          # ignore
+        end
+
+        # Replace min ruby dev token if present
+        begin
+          if min_dev_ruby && !min_dev_ruby.to_s.empty? && c.include?("{K_D_MIN_DEV_RUBY}")
+            c = c.gsub("{K_D_MIN_DEV_RUBY}", min_dev_ruby.to_s)
+          end
+        rescue StandardError => e
+          Kettle::Dev.debug_error(e, __method__)
+          # ignore
+        end
+
         # Special-case: yard-head link uses the gem name as a subdomain and must be dashes-only.
         # Apply this BEFORE other generic replacements so it isn't altered incorrectly.
         begin

data/lib/kettle/dev/version.rb

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

data/lib/kettle/dev.rb

@@ -22,6 +22,7 @@ module Kettle
     autoload :GitCommitFooter, "kettle/dev/git_commit_footer"
     autoload :InputAdapter, "kettle/dev/input_adapter"
     autoload :ReadmeBackers, "kettle/dev/readme_backers"
+    autoload :OpenCollectiveConfig, "kettle/dev/open_collective_config"
     autoload :ReleaseCLI, "kettle/dev/release_cli"
     autoload :PreReleaseCLI, "kettle/dev/pre_release_cli"
     autoload :SetupCLI, "kettle/dev/setup_cli"
@@ -61,6 +62,9 @@ module Kettle
     # Accepts 1, true, y, yes (any case).
     # @return [Regexp]
     ENV_TRUE_RE = /\A(1|true|y|yes)\z/i
+    # Absolute path to the root of the kettle-dev gem (repository root when working from source)
+    # @return [String]
+    GEM_ROOT = File.expand_path("../..", __dir__)
 
     @defaults = []
 

data/sig/kettle/dev/open_collective_config.rbs

@@ -0,0 +1,8 @@
+module Kettle
+  module Dev
+    module OpenCollectiveConfig
+      def self.yaml_path: (?String) -> String
+      def self.handle: (?required: bool, ?root: String, ?strict: bool) -> String?
+    end
+  end
+end

data/sig/kettle/dev/template_helpers.rbs

@@ -48,7 +48,9 @@ module Kettle
         gem_name: String,
         namespace: String,
         namespace_shield: String,
-        gem_shield: String
+        gem_shield: String,
+        ?funding_org: String?,
+        ?min_ruby: String?
       ) -> String
 
       # Parse gemspec metadata and derive useful strings
@@ -77,8 +79,6 @@ module Kettle
         bindir: String,
         executables: Array[String],
       }
-
-      def apply_common_replacements: () -> untyped
     end
   end
 end

data/sig/kettle/dev.rbs

@@ -12,6 +12,7 @@ module Kettle
     REQUIRE_BENCH: bool
     RUNNING_AS: String
     ENV_TRUE_RE: Regexp
+    GEM_ROOT: String
 
     # Singleton methods
     def self.install_tasks: () -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 1.1.22
+  version: 1.1.24
 platform: ruby
 authors:
 - Peter H. Boling
@@ -215,6 +215,17 @@ extra_rdoc_files:
 - RUBOCOP.md
 - SECURITY.md
 files:
+- "./.aiignore.example"
+- "./.env.local.example"
+- "./.gitlab-ci.yml.example"
+- "./.opencollective.yml.example"
+- "./.simplecov.example"
+- "./Appraisals.example"
+- "./CHANGELOG.md.example"
+- "./Gemfile.example"
+- "./README.md.example"
+- "./Rakefile.example"
+- "./kettle-dev.gemspec.example"
 - ".aiignore.example"
 - ".devcontainer/devcontainer.json"
 - ".env.local.example"
@@ -224,6 +235,7 @@ files:
 - ".git-hooks/footer-template.erb.txt"
 - ".git-hooks/prepare-commit-msg"
 - ".git-hooks/prepare-commit-msg.example"
+- ".github/.codecov.yml.example"
 - ".github/FUNDING.yml"
 - ".github/dependabot.yml"
 - ".github/workflows/ancient.yml"
@@ -233,6 +245,7 @@ files:
 - ".github/workflows/coverage.yml"
 - ".github/workflows/coverage.yml.example"
 - ".github/workflows/current.yml"
+- ".github/workflows/current.yml.example"
 - ".github/workflows/dep-heads.yml"
 - ".github/workflows/dependency-review.yml"
 - ".github/workflows/discord-notifier.yml.example"
@@ -253,6 +266,7 @@ files:
 - ".gitlab-ci.yml.example"
 - ".junie/guidelines-rbs.md"
 - ".junie/guidelines.md"
+- ".junie/guidelines.md.example"
 - ".licenserc.yaml"
 - ".opencollective.yml"
 - ".opencollective.yml.example"
@@ -337,6 +351,7 @@ files:
 - lib/kettle/dev/git_commit_footer.rb
 - lib/kettle/dev/input_adapter.rb
 - lib/kettle/dev/modular_gemfiles.rb
+- lib/kettle/dev/open_collective_config.rb
 - lib/kettle/dev/pre_release_cli.rb
 - lib/kettle/dev/rakelib/appraisal.rake
 - lib/kettle/dev/rakelib/bench.rake
@@ -372,6 +387,7 @@ files:
 - sig/kettle/dev/git_commit_footer.rbs
 - sig/kettle/dev/input_adapter.rbs
 - sig/kettle/dev/modular_gemfiles.rbs
+- sig/kettle/dev/open_collective_config.rbs
 - sig/kettle/dev/pre_release_cli.rbs
 - sig/kettle/dev/readme_backers.rbs
 - sig/kettle/dev/release_cli.rbs
@@ -388,10 +404,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.1.22
-  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.1.22/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.1.24
+  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.1.24/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.1.22
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.1.24
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev

metadata.gz.sig

@@ -1,3 +1,3 @@
-7������`5ADh�ox�~��cy[�(��S�Hӊ/\4d�?��m,_'�������ji�e�b�-�g���0��6���2j'iM0K��M&�X����JT�D�s�����a��m���l=�ڃ#����M�'����s��*@�DSl��-��p`�eU��v�i:����nڃq����e�\��H���L7x`����!�ې�&���2N�Zgt�Ug4�e�(�l�'80v���_��S��rZ��}�~��2�.�v�
-7�'���"x�)N
��+��p��i�����r�C�ۣm[��QY�0�U�
3�Ҹ
-T
+\[���}��In������qȲ,��n����?V��bx+���?《��X�M3~��!��h!�Ӷ�z���E,_��I~�7H�'��=�ٵ���Pƕ�V�t�,�hK�8�(�U�<rt�s�!YQ�4��n�\�E�2L��h��F\E�M��������! 8v���r}d#��J|a���yr
+����m��I��}ETW����p���G�	��KH�(���pS~�k���eS#��5_1;��I�I�������tFi��pB`�/��-�Jf�[��<��r��a��
+"�@+Ks�eM�޿AҾ�,��_e9��689�K&?�3�t�Q��m���Q�?*�F�6d���X��
��*p&��)�A�,�绒�$�