kettle-jem-appraisals 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78ffff1b9845b058f35013adea659ae8a8b03f21c522494122255f1774f0913
-  data.tar.gz: 4411573fb6ebf9808efdf42d0d4be6496cdd18f07a9c637d326075a5314c2f14
+  metadata.gz: 55c26a21775e32a64b50f493b789920cdcb15a9f142be11204c06c6c012bb411
+  data.tar.gz: 94556e63d682de6d157ffe647a78cda96cd3fcafc362bcf4f1234a23ed8dd8b9
 SHA512:
-  metadata.gz: c9aa86d8864d7204613bf89db1f78811b944d7cbe842f2f5e6c4bd95448bbb500bcfcd201c6e5519532a85fa9acf3974592f642651f793fd7317db80f38823df
-  data.tar.gz: e07bd405386de50eb128ab77984ae8eb47786f80c180fa3a8e8e8ba76503e8d3bbb306906eb9cffb25166ffbb9fb30cd06a9296c4581d606792a49d8f89bd130
+  metadata.gz: 35de41e63c518c3b0501e00b957f553a61eccecd4367d1861a12c4a4afc9ef4f788a5bfb640610d1810e576f1ee59cafb684895a2cecd91b40af3d87268421c7
+  data.tar.gz: 958ffe7e6d18a08a5b9241ba58c90047d6610bc7fce5f8cdef64a0287c617c7f882ca8b1829e056990e73ea970d5d067edc05bf7b5b3eccb85a0f86519b5cd5f

data/CHANGELOG.md

@@ -30,6 +30,67 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.1.6] - 2026-09-29
+
+- TAG: [v0.1.6][0.1.6t]
+- COVERAGE: 95.69% -- 976/1020 lines in 15 files
+- BRANCH COVERAGE: 83.93% -- 282/336 branches in 15 files
+- 92.13% documented
+
+### Added
+
+- kettle-jem-template-20260913-001 - Templating now also surfaces a review
+  entry in `dependency_conflicts.resolve` when a direct development
+  dependency doesn't support one or more of this project's declared
+  `engines:` and has no template-managed modular home (e.g. `sqlite3` on
+  `jruby`). Review each entry and pick a resolution per the project's own
+  engine support needs.
+
+### Changed
+
+- [kc] kettle-jem/prepare: updated 14 project files:
+  - dependencies (14)
+
+- [kc] kettle-jem/template: updated 17 project files:
+  - code and tests (2)
+  - dependencies (2)
+  - documentation (1)
+  - other (2)
+  - workflows (10)
+
+### Fixed
+
+- Restore the released kettle-jem dependency floor after local templating raised it to an unreleased version.
+
+- Skip the style-only RuboCop toolchain in the Ruby 3.2 appraisal bundle.
+
+- Launch the generated appraisal binstub through the active Ruby interpreter so matrix resolution works on Windows.
+
+## [0.1.5] - 2026-09-19
+
+- TAG: [v0.1.5][0.1.5t]
+- COVERAGE: 95.68% -- 975/1019 lines in 15 files
+- BRANCH COVERAGE: 83.93% -- 282/336 branches in 15 files
+- 92.13% documented
+
+### Added
+
+- Security floors from kettle-rb `Kettle::Rb::GemFloors` in generated per-version gemfiles for tracked gems and their tracked sub-dependencies (e.g. `gem "activerecord", "~> 7.1.0", ">= 7.1.6"`)
+- `--resolve` warns, and generated gemfiles carry a `# kettle-rb:` comment, when a series has advisories no release fixes or an exact patch version is below its security floor
+- Runtime dependency on kettle-rb `>= 0.1.14`
+
+### Changed
+
+- ActiveRecord support gemfiles take their sqlite3 requirements from kettle-rb `Kettle::Rb::GemDependencies` instead of hardcoded ranges, are written per requirement under `gemfiles/modular/activerecord_support/` (e.g. `v6.0.gemfile` for ActiveRecord 6.0–7.0), and only for the ActiveRecord versions in the matrix
+- `activerecord_support.gemfile` / `activerecord_support_modern.gemfile` generated by 0.1.4 and earlier are removed (hand-maintained ones are kept)
+
+### Fixed
+
+- `--resolve` now exits non-zero when `bin/appraisal generate` fails, instead of reporting "Resolve complete"
+- `-h`/`--help` prints usage instead of running scaffold mode, and unknown options are rejected before any file is written
+- A selected version whose optimal Ruby bucket falls below the project's Ruby floor (e.g. activerecord 5.2 for a gem requiring Ruby >= 2.5) is assigned to the lowest bucket that can run it instead of being silently dropped; selected versions that still cannot be assigned are reported
+- `semver` mode includes the lowest minor allowed by a gem's `requirements` (e.g. activerecord 7.0 for `>= 7.0`)
+
 ## [0.1.4] - 2026-09-14
 
 - TAG: [v0.1.4][0.1.4t]
@@ -194,7 +255,11 @@ Please file a bug if you notice a violation of semantic versioning.
 - kettle-jem-template-20260802-001 - Devcontainer JSON files now merge as JSONC,
   preserving comments and trailing commas during template updates.
 
-[Unreleased]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.6...HEAD
+[0.1.6]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.5...v0.1.6
+[0.1.6t]: https://github.com/appraisal-rb/kettle-jem-appraisals/releases/tag/v0.1.6
+[0.1.5]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.4...v0.1.5
+[0.1.5t]: https://github.com/appraisal-rb/kettle-jem-appraisals/releases/tag/v0.1.5
 [0.1.4]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.3...v0.1.4
 [0.1.4t]: https://github.com/appraisal-rb/kettle-jem-appraisals/releases/tag/v0.1.4
 [0.1.3]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.2...v0.1.3

data/README.md

@@ -65,7 +65,7 @@ targets **`appraisal`** (which does not support `eval_gemfile`, and only support
 
 Compatible with MRI Ruby 4.0.0+, and JRuby.
 CI workflows and Appraisals are generated for MRI Ruby 4.0.0+.
-This test floor is configured by `ruby.test_minimum` in `.structuredmerge/kettle-jem.yml` and
+This test floor is configured by `ruby.test_minimum` in `.kettle-jem.yml` and
 may be higher than the gem's runtime compatibility floor when legacy Rubies are
 not practical for the current toolchain.
 
@@ -381,19 +381,24 @@ database driver whose gem differs per engine and per ActiveRecord version:
 `sqlite3` on MRI/TruffleRuby, `activerecord-jdbcsqlite3-adapter` (plus
 `bigdecimal`) on JRuby. When `activerecord` is a tier1 gem, `--resolve`:
 
-- writes `gemfiles/modular/activerecord_support.gemfile` (`sqlite3` 1.4.x, for
-  ActiveRecord < 7.2) and `gemfiles/modular/activerecord_support_modern.gemfile`
-  (`sqlite3` >= 2.1, for ActiveRecord >= 7.2), each with a JRuby platform block
-  for the JDBC adapter, whose release series tracks ActiveRecord so Bundler picks
+- writes one support gemfile under `gemfiles/modular/activerecord_support/` for
+  each `sqlite3` requirement the matrix's ActiveRecord versions need. The
+  requirements come from [kettle-rb][kettle-rb]'s `Kettle::Rb::GemDependencies`
+  (what each ActiveRecord series' sqlite3 adapter declares), and each file is
+  named after the oldest ActiveRecord series sharing the requirement (for
+  example `v6.0.gemfile` covers 6.0–7.0 with `sqlite3 ~> 1.4`, and `v8.0.gemfile`
+  covers 8.0+ with `sqlite3 >= 2.1`). Each file has a JRuby platform block for
+  the JDBC adapter, whose release series tracks ActiveRecord so Bundler picks
   the matching adapter;
 - adds the matching support gemfile to each generated entry, based on that
-  entry's ActiveRecord version (unless `appraisal_gemfiles` already lists one of
-  them).
+  entry's ActiveRecord version (unless `appraisal_gemfiles` already lists one);
+- removes `activerecord_support.gemfile` / `activerecord_support_modern.gemfile`
+  written by kettle-jem-appraisals 0.1.4 and earlier.
 
 Existing support gemfiles that do not carry the `# Generated by
 kettle-jem-appraisals` header are treated as hand-maintained and left untouched.
 Set `activerecord_support: false` to opt out entirely (for example, when the
-suite uses PostgreSQL). Point the root `Gemfile` at the modern support gemfile
+suite uses PostgreSQL). Point the root `Gemfile` at the newest support gemfile
 via kettle-jem's `test_bundle.gemfiles`, and select the JDBC adapter in your spec
 helper on JRuby:
 
@@ -408,6 +413,21 @@ adapter = (RUBY_PLATFORM == "java" && ActiveRecord.version < Gem::Version.new("7
 ActiveRecord::Base.establish_connection(adapter: adapter, database: ":memory:")
 ```
 
+### Security floors
+
+Per-version gemfiles for gems tracked by kettle-rb's `Kettle::Rb::GemFloors`
+(activemodel, activerecord, activesupport, sqlite3) require the minor series'
+security floor, e.g. `gem "activerecord", "~> 7.1.0", ">= 7.1.6"`: the newest
+patch that keeps the series' original minimum Ruby, never below a patched
+advisory. Tracked sub-dependencies get their floor too. Exact patch versions
+(`patch` mode) stay pinned.
+
+When a series has advisories that no release fixes (for example activerecord
+5.2–7.0 and CVE-2025-55193), or an exact patch version is below its floor,
+`--resolve` warns and the generated gemfile carries a `# kettle-rb:` comment.
+Support gemfiles likewise note sqlite3 advisories that no allowed sqlite3
+release fixes. Update kettle-rb to pick up new advisories.
+
 ### Optimal bucket assignment
 
 Rather than cross-producting every gem version with every Ruby series,
@@ -450,14 +470,17 @@ This generates:
 
 ### CLI flags
 
-| Flag         | Description                                 |
-|--------------|---------------------------------------------|
-| `--scaffold` | Force scaffold mode (even if config exists) |
-| `--resolve`  | Force resolve mode                          |
-| `--force`    | Bypass freshness TTL and re-resolve         |
+| Flag              | Description                                 |
+|-------------------|---------------------------------------------|
+| `--scaffold`      | Force scaffold mode (even if config exists) |
+| `--resolve`       | Force resolve mode                          |
+| `--force`         | Bypass freshness TTL and re-resolve         |
+| `-v`, `--version` | Print the version and exit                  |
+| `-h`, `--help`    | Print usage and exit                        |
 
-Without flags, the CLI auto-detects: scaffold if no versions are configured,
-resolve otherwise.
+Without a mode flag, the CLI auto-detects: scaffold if no versions are configured,
+resolve otherwise. Unknown options exit with an error before any file is written.
+`--resolve` exits non-zero when `bin/appraisal generate` fails.
 
 ### Re-resolving
 
@@ -651,6 +674,7 @@ Thanks for RTFM. ☺️
 [✉️ruby-forum]: https://www.rubyforum.org/tag/appraisal-rb
 
 [✇bundle-group-pattern]: https://gist.github.com/pboling/4564780
+[kettle-rb]: https://github.com/kettle-dev/kettle-rb
 [⛳️gem-namespace]: https://github.com/appraisal-rb/kettle-jem-appraisals
 [⛳️namespace-img]: https://img.shields.io/badge/namespace-Kettle::Jem::Appraisals-3C2D2D.svg?style=square&logo=ruby&logoColor=white
 [⛳️gem-name]: https://clickgems.clickhouse.com/dashboard/kettle-jem-appraisals
@@ -756,7 +780,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-0.897-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.020-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/appraisal-rb/kettle-jem-appraisals/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/lib/kettle/jem/appraisals/active_record_support_gemfile_generator.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "kettle/rb"
 
 module Kettle
   module Jem
@@ -9,8 +10,13 @@ module Kettle
       # database driver on every engine: +sqlite3+ on MRI/TruffleRuby and
       # +activerecord-jdbcsqlite3-adapter+ (plus +bigdecimal+) on JRuby.
       #
-      # Two variants exist because +sqlite3+ 2.x is only supported by
-      # ActiveRecord >= 7.2, while older ActiveRecord needs the 1.4 series.
+      # The sqlite3 requirement comes from +Kettle::Rb::GemDependencies+, which
+      # records what each ActiveRecord series' sqlite3 adapter declares. One
+      # support gemfile is written per run of consecutive ActiveRecord series
+      # sharing a requirement, named after the oldest series in the run
+      # (+gemfiles/modular/activerecord_support/v6.0.gemfile+ covers 6.0–7.0).
+      # ActiveRecord newer than the recorded series uses the newest run.
+      #
       # The JDBC adapter's release series tracks ActiveRecord (52.x, 61.x, 72.x…),
       # so an open requirement lets Bundler pick the adapter matching the
       # resolved ActiveRecord.
@@ -20,33 +26,32 @@ module Kettle
       #
       # @example
       #   generator = ActiveRecordSupportGemfileGenerator.new(base_dir: "/path/to/gem")
-      #   generator.generate
-      #   generator.eval_path_for("7.1.6") #=> "modular/activerecord_support.gemfile"
+      #   generator.generate(["7.1", "8.0"])
+      #   generator.eval_path_for("7.1.6") #=> "modular/activerecord_support/v7.1.gemfile"
       class ActiveRecordSupportGemfileGenerator
         # @return [String] header marking a support gemfile as generated (and safe to regenerate)
         GENERATED_HEADER = "# Generated by kettle-jem-appraisals"
 
-        # @return [String] support gemfile for ActiveRecord below {MODERN_ACTIVERECORD}
-        LEGACY_PATH = "gemfiles/modular/activerecord_support.gemfile"
-
-        # @return [String] support gemfile for ActiveRecord at or above {MODERN_ACTIVERECORD}
-        MODERN_PATH = "gemfiles/modular/activerecord_support_modern.gemfile"
+        # @return [String] directory holding the support gemfiles
+        SUPPORT_DIR = "gemfiles/modular/activerecord_support"
 
-        # @return [Gem::Version] first ActiveRecord release that supports sqlite3 2.x
-        MODERN_ACTIVERECORD = Gem::Version.new("7.2")
+        # @return [String] support gemfile for ActiveRecord older than every recorded series
+        UNKNOWN_PATH = "#{SUPPORT_DIR}/unknown.gemfile"
 
-        # @return [Hash{String => Hash}] per-variant sqlite3 requirements and description
-        VARIANTS = {
-          LEGACY_PATH => {sqlite3: [">= 1.4", "< 1.5"], label: "ActiveRecord < 7.2"},
-          MODERN_PATH => {sqlite3: [">= 2.1"], label: "ActiveRecord >= 7.2"}
-        }.freeze
+        # @return [Array<String>] support gemfiles written by kettle-jem-appraisals 0.1.4 and earlier
+        LEGACY_PATHS = [
+          "gemfiles/modular/activerecord_support.gemfile",
+          "gemfiles/modular/activerecord_support_modern.gemfile"
+        ].freeze
 
         class << self
           # @param path [String] a gemfile path, with or without the leading +gemfiles/+
-          # @return [Boolean] whether +path+ names one of the ActiveRecord support gemfiles
+          # @return [Boolean] whether +path+ names an ActiveRecord support gemfile
           def support_gemfile?(path)
             normalized = path.to_s.strip.sub(%r{\Agemfiles/}, "")
-            VARIANTS.keys.any? { |variant| variant.delete_prefix("gemfiles/") == normalized }
+            return true if normalized.start_with?("#{SUPPORT_DIR.delete_prefix("gemfiles/")}/")
+
+            LEGACY_PATHS.any? { |legacy| legacy.delete_prefix("gemfiles/") == normalized }
           end
         end
 
@@ -58,40 +63,121 @@ module Kettle
           @base_dir = base_dir
         end
 
-        # Writes both support gemfiles, skipping any hand-maintained file.
+        # Writes the support gemfile needed by each ActiveRecord version, skipping
+        # hand-maintained files, and removes support gemfiles generated by
+        # kettle-jem-appraisals 0.1.4 and earlier.
         #
-        # @return [Hash{String => Symbol}] relative path => +:written+ or +:kept+
-        def generate
-          VARIANTS.each_with_object({}) do |(relative_path, variant), results|
+        # @param activerecord_versions [Array<String>] ActiveRecord versions in the matrix
+        # @return [Hash{String => Symbol}] relative path => +:written+, +:kept+, or +:removed+
+        def generate(activerecord_versions)
+          results = {}
+          activerecord_versions.map { |version| group_for(version) }.uniq.each do |group|
+            relative_path = path_for(group)
             absolute = File.join(base_dir, relative_path)
-            if File.exist?(absolute) && !File.read(absolute).include?(GENERATED_HEADER)
+            if hand_maintained?(absolute)
               results[relative_path] = :kept
               next
             end
 
             FileUtils.mkdir_p(File.dirname(absolute))
-            File.write(absolute, build_content(variant))
+            File.write(absolute, build_content(group))
             results[relative_path] = :written
           end
+
+          LEGACY_PATHS.each do |relative_path|
+            absolute = File.join(base_dir, relative_path)
+            next unless File.exist?(absolute) && !hand_maintained?(absolute)
+
+            FileUtils.rm_f(absolute)
+            results[relative_path] = :removed
+          end
+          results
         end
 
         # @param activerecord_version [String, Gem::Version] the entry's ActiveRecord version
         # @return [String] the matching support gemfile, relative to +gemfiles/+ (for +eval_gemfile+)
         def eval_path_for(activerecord_version)
-          path = (Gem::Version.new(activerecord_version.to_s) >= MODERN_ACTIVERECORD) ? MODERN_PATH : LEGACY_PATH
-          path.delete_prefix("gemfiles/")
+          path_for(group_for(activerecord_version)).delete_prefix("gemfiles/")
+        end
+
+        # @param activerecord_version [String, Gem::Version]
+        # @return [Array<String>] the sqlite3 requirements for that ActiveRecord version
+        def sqlite3_requirements(activerecord_version)
+          group = group_for(activerecord_version)
+          group ? group.first.requirements : []
+        end
+
+        # Advisories that affect every sqlite3 series the requirements allow.
+        #
+        # @param activerecord_version [String, Gem::Version]
+        # @return [Array<String>] advisory ids; empty when a fixed sqlite3 release is allowed
+        def unfixed_sqlite3_advisories(activerecord_version)
+          requirement = Gem::Requirement.new(*sqlite3_requirements(activerecord_version))
+          allowed = Kettle::Rb::GemFloors.entries_for("sqlite3").select { |entry|
+            requirement.satisfied_by?(Gem::Version.new(entry.floor))
+          }
+          return [] if allowed.empty? || allowed.any? { |entry| entry.unpatched_advisories.empty? }
+
+          allowed.flat_map(&:unpatched_advisories).uniq.sort
         end
 
         private
 
-        def build_content(variant)
-          sqlite3 = [%("sqlite3"), *variant.fetch(:sqlite3).map(&:inspect), "platforms: [:ruby]"].join(", ")
+        # Runs of consecutive ActiveRecord series with identical sqlite3 requirements.
+        def groups
+          @groups ||= Kettle::Rb::GemDependencies.entries_for("activerecord", "sqlite3")
+            .sort_by { |entry| Gem::Version.new(entry.series) }
+            .chunk_while { |older, newer| older.requirements == newer.requirements }
+            .to_a
+        end
+
+        def group_for(activerecord_version)
+          series = Kettle::Rb::GemFloors.series_for(activerecord_version)
+          return unless series
+
+          version = Gem::Version.new(series)
+          groups.reverse.find { |group| Gem::Version.new(group.first.series) <= version }
+        end
+
+        def path_for(group)
+          group ? "#{SUPPORT_DIR}/v#{group.first.series}.gemfile" : UNKNOWN_PATH
+        end
+
+        def hand_maintained?(absolute)
+          File.exist?(absolute) && !File.read(absolute).include?(GENERATED_HEADER)
+        end
+
+        def label(group)
+          return "ActiveRecord without recorded sqlite3 requirements" unless group
+
+          first = group.first.series
+          last = group.last.series
+          range =
+            if group.equal?(groups.last)
+              "#{first}+"
+            elsif first == last
+              first
+            else
+              "#{first}–#{last}"
+            end
+          "ActiveRecord #{range}"
+        end
+
+        def build_content(group)
+          requirements = group ? group.first.requirements : []
+          sqlite3 = [%("sqlite3"), *requirements.map(&:inspect), "platforms: [:ruby]"].join(", ")
+          notes = []
+          notes << "# sqlite3 requirement from kettle-rb: #{group.last.source}" if group
+          unfixed = group ? unfixed_sqlite3_advisories(group.first.series) : []
+          notes << "# kettle-rb: no sqlite3 release allowed here fixes #{unfixed.join(", ")}" unless unfixed.empty?
+
           <<~GEMFILE
             # frozen_string_literal: true
 
             #{GENERATED_HEADER}
-            # Database drivers for #{variant.fetch(:label)}: sqlite3 on MRI/TruffleRuby,
+            # Database drivers for #{label(group)}: sqlite3 on MRI/TruffleRuby,
             # activerecord-jdbcsqlite3-adapter on JRuby (its release series tracks ActiveRecord).
+            #{notes.join("\n")}
             gem #{sqlite3}
 
             platforms :jruby do

data/lib/kettle/jem/appraisals/cli.rb

@@ -2,6 +2,7 @@
 
 require "yaml"
 require "fileutils"
+require "rbconfig"
 require "rubygems/specification"
 
 module Kettle
@@ -59,10 +60,49 @@ module Kettle
           end
         end
 
+        # @return [Array<String>] command-line options accepted by {#run}
+        OPTIONS = %w[--scaffold --resolve --force -v --version -h --help].freeze
+
+        # @return [String] usage text printed by +--help+
+        USAGE = <<~USAGE
+          Usage: kettle-jem-appraisals [--scaffold | --resolve] [--force]
+
+          Generates an Appraisal matrix for the gem in the current directory.
+          Without a mode flag, scaffolds appraisal_matrix in #{CONFIG_FILE} when it
+          has no resolved versions, and resolves it otherwise.
+
+          Options:
+            --scaffold     Force scaffold mode (even if config exists)
+            --resolve      Force resolve mode
+            --force        Bypass freshness TTL and re-resolve
+            -v, --version  Print the version and exit
+            -h, --help     Print this help and exit
+        USAGE
+
         # Detects the appropriate mode and dispatches to scaffold or resolve.
         #
+        # Prints usage for +-h+/+--help+ and the version for +-v+/+--version+
+        # without touching any files, and exits when given an unknown option.
+        #
         # @return [void]
         def run
+          if args.include?("-h") || args.include?("--help")
+            puts USAGE
+            return
+          end
+
+          if args.include?("-v") || args.include?("--version")
+            puts Version::VERSION
+            return
+          end
+
+          unknown = args - OPTIONS
+          unless unknown.empty?
+            warn "Unknown option(s): #{unknown.join(" ")}"
+            warn USAGE
+            exit(1)
+          end
+
           mode = detect_mode
           case mode
           when :scaffold
@@ -267,6 +307,7 @@ module Kettle
           )
           annotate_extra_gemfiles(appraisal_entries, matrix_extra_gemfiles(matrix))
           annotate_activerecord_support(appraisal_entries, tier1_gems, matrix)
+          warn_security_advisories(appraisal_entries)
           annotate_standard_appraisal_collapses(appraisal_entries, bucket_ranges, matrix)
 
           puts "  📊 Generated #{appraisal_entries.size} appraisal entries"
@@ -295,19 +336,27 @@ module Kettle
           config[APPRAISAL_MATRIX_KEY] = matrix
           write_config(config)
 
-          # Run bin/appraisal generate
-          if File.exist?(File.join(project_dir, "bin", "appraisal"))
-            puts "  🔧 Running bin/appraisal generate..."
-            system("bin/appraisal", "generate", chdir: project_dir)
-          else
-            puts "  ⚠️  bin/appraisal not found — run `bundle binstubs appraisal2` then `bin/appraisal generate`"
-          end
+          run_appraisal_generate
 
           puts "  ✅ Resolve complete"
         end
 
         # ── Helpers ──────────────────────────────────────────────────────
 
+        # Runs +bin/appraisal generate+ when the binstub exists, exiting when it fails.
+        def run_appraisal_generate
+          unless File.exist?(File.join(project_dir, "bin", "appraisal"))
+            puts "  ⚠️  bin/appraisal not found — run `bundle binstubs appraisal2` then `bin/appraisal generate`"
+            return
+          end
+
+          puts "  🔧 Running bin/appraisal generate..."
+          return if system(RbConfig.ruby, "bin/appraisal", "generate", chdir: project_dir)
+
+          warn "  ❌ bin/appraisal generate failed (#{$?.inspect}); Appraisals and gemfiles/ may be incomplete"
+          exit(1)
+        end
+
         # Removes stale kja-* flat gemfiles from gemfiles/ that are no longer
         # in the current matrix. Only touches files matching the PREFIX pattern.
         def cleanup_stale_gemfiles(current_entries)
@@ -393,6 +442,14 @@ module Kettle
         # that version is the best choice).
         #
         # Tier2 versions are all compatible versions for each tier1's bucket.
+        # Reports selected versions that could not be assigned to any Ruby bucket.
+        def warn_unassigned_versions(gem_name, versions, assignments)
+          missing = versions - assignments.map { |assignment| assignment[:version] }
+          return if missing.empty?
+
+          warn "    ⚠️  #{gem_name} #{missing.join(", ")} not assigned to any Ruby bucket (unknown required_ruby_version?); left out of the matrix"
+        end
+
         def build_matrix(tier1_gems, tier2_gems, ruby_series, bucket_ranges, all_seams, all_versions_by_gem, resolver, builder, gemfile_gen, sub_resolver)
           entries = []
 
@@ -415,6 +472,7 @@ module Kettle
               puts "    ⚠️  No bucket assignments for #{t1_name}, falling back to latest bucket"
               t1_assignments = t1_versions.map { |v| {version: v, bucket: ruby_series.last} }
             end
+            warn_unassigned_versions(t1_name, t1_versions, t1_assignments)
 
             # Show assignments
             t1_assignments.each do |a|
@@ -609,8 +667,9 @@ module Kettle
           end.uniq
         end
 
-        # Generates the ActiveRecord database support gemfiles and adds the one
-        # matching each ActiveRecord entry's version to its extra gemfiles.
+        # Generates the ActiveRecord database support gemfiles the matrix needs and
+        # adds the one matching each ActiveRecord entry's version to its extra gemfiles.
+        # Warns when no sqlite3 release an entry's support gemfile allows fixes an advisory.
         # Skipped when disabled via +activerecord_support+, when activerecord is not
         # a tier1 gem, or when +appraisal_gemfiles+ already names a support gemfile.
         def annotate_activerecord_support(appraisal_entries, tier1_gems, matrix)
@@ -618,16 +677,43 @@ module Kettle
           return unless tier1_gems.any? { |gem_config| gem_config["name"] == "activerecord" }
           return if matrix_extra_gemfiles(matrix).any? { |path| ActiveRecordSupportGemfileGenerator.support_gemfile?(path) }
 
+          activerecord_entries = appraisal_entries.select { |entry| entry[:tier1_name] == "activerecord" && entry[:tier1_version] }
+          versions = activerecord_entries.map { |entry| entry[:tier1_version] }
           generator = ActiveRecordSupportGemfileGenerator.new(base_dir: project_dir)
-          generator.generate.each do |path, status|
-            puts "  🗄️  #{(status == :written) ? "Wrote" : "Kept hand-maintained"} #{path}"
+          generator.generate(versions).each do |path, status|
+            label = {written: "Wrote", kept: "Kept hand-maintained", removed: "Removed stale generated"}.fetch(status)
+            puts "  🗄️  #{label} #{path}"
           end
-          appraisal_entries.each do |entry|
-            next unless entry[:tier1_name] == "activerecord" && entry[:tier1_version]
-
+          activerecord_entries.each do |entry|
             support = generator.eval_path_for(entry[:tier1_version])
             entry[:extra_gemfiles] = [support, *Array(entry[:extra_gemfiles])].uniq
           end
+          versions.group_by { |version| generator.eval_path_for(version) }.each do |path, grouped|
+            unfixed = generator.unfixed_sqlite3_advisories(grouped.first)
+            next if unfixed.empty?
+
+            warn "  ⚠️  kettle-rb: no sqlite3 release allowed for activerecord #{grouped.uniq.join(", ")} (#{path}) fixes #{unfixed.join(", ")}"
+          end
+        end
+
+        # Warns about tracked gem versions in the matrix whose minor series has
+        # advisories no release fixes, or whose exact patch version is below the
+        # series' security floor (from +Kettle::Rb::GemFloors+).
+        def warn_security_advisories(appraisal_entries)
+          pairs = appraisal_entries.flat_map { |entry|
+            [[entry[:tier1_name], entry[:tier1_version]], [entry[:tier2_name], entry[:tier2_version]]]
+          }
+          messages = pairs.filter_map { |name, version| [name, version] if name && version && Kettle::Rb::GemFloors.tracked?(name) }.flat_map { |name, version|
+            notes = []
+            unpatched = Kettle::Rb::GemFloors.unpatched_advisories(name, version)
+            notes << "no #{name} #{Kettle::Rb::GemFloors.series_for(version)} release fixes #{unpatched.join(", ")}" unless unpatched.empty?
+            floor = Kettle::Rb::GemFloors.floor(name, version)
+            if floor && version.to_s.split(".").length >= 3 && Gem::Version.new(floor) > Gem::Version.new(version.to_s)
+              notes << "#{name} #{version} is pinned below the security floor #{floor}"
+            end
+            notes
+          }
+          messages.uniq.each { |message| warn "  ⚠️  kettle-rb: #{message}" }
         end
 
         def activerecord_support_enabled?(matrix)

data/lib/kettle/jem/appraisals/matrix_builder.rb

@@ -115,7 +115,11 @@ module Kettle
             next_seam_ruby = find_next_seam_ruby(ver, ver_min_ruby, all_versions, version_min_ruby)
 
             bucket = if next_seam_ruby
-              find_bucket_below(next_seam_ruby, buckets, bucket_ranges)
+              # When the next seam is at or below the project's Ruby floor, no
+              # bucket sits below it; test this version on the lowest bucket
+              # that can run it instead of dropping it.
+              find_bucket_below(next_seam_ruby, buckets, bucket_ranges) ||
+                find_lowest_runnable_bucket(ver_min_ruby, buckets, bucket_ranges)
             else
               # This is in the latest seam range — catch-all bucket
               buckets.last
@@ -130,6 +134,14 @@ module Kettle
 
         private
 
+        # Finds the lowest bucket whose Ruby ceiling can run a version requiring +min_ruby+.
+        def find_lowest_runnable_bucket(min_ruby, buckets, bucket_ranges)
+          buckets.find { |bucket|
+            range = bucket_ranges[bucket]
+            range && range[:ceiling] >= min_ruby
+          }
+        end
+
         # One entry per major version (the latest minor of each).
         def select_major(by_major)
           by_major.map { |entry| entry[:minors].last }
@@ -190,6 +202,9 @@ module Kettle
             end
           end
 
+          # Explicit requirements declare the oldest supported version, so test it.
+          versions << by_major.first[:minors].first if requirements && !requirements.empty?
+
           versions.uniq.sort_by { |v| Gem::Version.new(v) }
         end
 

data/lib/kettle/jem/appraisals/modular_gemfile_generator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "kettle/rb"
+
 module Kettle
   module Jem
     module Appraisals
@@ -8,6 +10,11 @@ module Kettle
       # Creates per-version gemfiles organized by gem name and Ruby series:
       #   +gemfiles/modular/{gem_name}/{ruby_series}/v{version}.gemfile+
       #
+      # Gems tracked by +Kettle::Rb::GemFloors+ get their minor series' security
+      # floor (e.g. +"~> 7.1.0", ">= 7.1.6"+). Exact patch versions stay pinned.
+      # A comment notes advisories that no release in the series fixes, and an
+      # exact patch version below the floor.
+      #
       # @example
       #   gen = ModularGemfileGenerator.new(base_dir: "/path/to/project")
       #   gen.generate(gem_name: "activerecord", version: "7.1", ruby_series: "r3")
@@ -66,15 +73,11 @@ module Kettle
         private
 
         def build_content(gem_name, version, sub_deps)
-          lines = [
-            "# frozen_string_literal: true",
-            "",
-            "# Generated by kettle-jem-appraisals",
-            "gem #{gem_name.inspect}, #{version_requirement(version).inspect}"
-          ]
+          lines = header_lines
+          lines.concat(gem_lines(gem_name, version, pinned_requirements(gem_name, version)))
 
           sub_deps.each do |dep_name, dep_version|
-            lines << "gem #{dep_name.inspect}, \"~> #{dep_version}\""
+            lines.concat(gem_lines(dep_name, dep_version, floored_requirements(dep_name, dep_version, ["~> #{dep_version}"])))
           end
 
           lines << ""
@@ -82,19 +85,64 @@ module Kettle
         end
 
         def build_tier2_content(gem_name, version)
-          lines = [
+          lines = header_lines
+          lines.concat(gem_lines(gem_name, version, pinned_requirements(gem_name, version)))
+          lines << ""
+          "#{lines.join("\n")}\n"
+        end
+
+        def header_lines
+          [
             "# frozen_string_literal: true",
             "",
-            "# Generated by kettle-jem-appraisals",
-            "gem #{gem_name.inspect}, #{version_requirement(version).inspect}",
-            ""
+            "# Generated by kettle-jem-appraisals"
           ]
-          "#{lines.join("\n")}\n"
+        end
+
+        def gem_lines(gem_name, version, requirements)
+          advisory_notes(gem_name, version, requirements) + ["gem #{[gem_name, *requirements].map(&:inspect).join(", ")}"]
+        end
+
+        # Minor versions get the series' security floor; exact patch versions stay pinned.
+        def pinned_requirements(gem_name, version)
+          requirement = version_requirement(version)
+          return [requirement] if exact_patch?(version)
+
+          floored_requirements(gem_name, version, [requirement])
+        end
+
+        def floored_requirements(gem_name, version, requirements)
+          floor = floor_above(gem_name, version)
+          floor ? requirements + [">= #{floor}"] : requirements
+        end
+
+        def advisory_notes(gem_name, version, requirements)
+          notes = []
+          unpatched = Kettle::Rb::GemFloors.unpatched_advisories(gem_name, version)
+          unless unpatched.empty?
+            series = Kettle::Rb::GemFloors.series_for(version)
+            notes << "# kettle-rb: no #{gem_name} #{series} release fixes #{unpatched.join(", ")}"
+          end
+
+          floor = floor_above(gem_name, version)
+          if floor && !requirements.include?(">= #{floor}")
+            notes << "# kettle-rb: #{gem_name} #{version} is below the #{gem_name} security floor #{floor}"
+          end
+          notes
+        end
+
+        # @return [String, nil] the security floor when it is newer than +version+
+        def floor_above(gem_name, version)
+          floor = Kettle::Rb::GemFloors.floor(gem_name, version)
+          floor if floor && Gem::Version.new(floor) > Gem::Version.new(version)
+        end
+
+        def exact_patch?(version)
+          version.to_s.split(".").length >= 3
         end
 
         def version_requirement(version)
-          segments = version.to_s.split(".")
-          if segments.length >= 3
+          if exact_patch?(version)
             "~> #{version}"
           else
             "~> #{version}.0"

data/lib/kettle/jem/appraisals/version.rb

@@ -6,7 +6,7 @@ module Kettle
       # Version namespace for this gem.
       module Version
         # Current gem version.
-        VERSION = "0.1.4"
+        VERSION = "0.1.6"
       end
       # Current gem version exposed at the traditional constant location.
       VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/jem/appraisals.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "kettle/jem"
+require "kettle/rb"
 
 module Kettle
   module Jem

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-jem-appraisals
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Peter H. Boling
@@ -57,6 +57,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.28
+- !ruby/object:Gem::Dependency
+  name: kettle-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.14
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -86,7 +106,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: 3.1.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -96,7 +116,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: 3.1.5
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -174,7 +194,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -184,7 +204,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -194,7 +214,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.21
+        version: 2.0.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -204,7 +224,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.21
+        version: 2.0.23
 - !ruby/object:Gem::Dependency
   name: turbo_tests2
   requirement: !ruby/object:Gem::Requirement
@@ -214,7 +234,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.7
+        version: 3.2.12
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -224,7 +244,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.7
+        version: 3.2.12
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -248,7 +268,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -258,7 +278,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.9
 - !ruby/object:Gem::Dependency
   name: gitmoji-regex
   requirement: !ruby/object:Gem::Requirement
@@ -268,7 +288,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.12
+        version: 2.0.13
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -278,7 +298,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.12
+        version: 2.0.13
 description: "\U0001F372 Kettle::Jem::Appraisals auto-generates CI test matrices from
   RubyGems API data. Scaffolds tier1/tier2 gem lists from gemspec, resolves version
   spreads per mode (major/minor/minor-minmax/semver), generates modular gemfiles and
@@ -315,10 +335,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-jem-appraisals.galtzo.com
-  source_code_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/tree/v0.1.4
-  changelog_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/blob/v0.1.4/CHANGELOG.md
+  source_code_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/tree/v0.1.6
+  changelog_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/blob/v0.1.6/CHANGELOG.md
   bug_tracker_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-jem-appraisals/0.1.4
+  documentation_uri: https://www.rubydoc.info/gems/kettle-jem-appraisals/0.1.6
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/wiki
   news_uri: https://www.railsbling.com/tags/kettle-jem-appraisals
@@ -349,7 +369,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: "\U0001F372 Auto-generate Appraisal matrices for kettle-jem managed gems"
 test_files: []