kettle-jem-appraisals 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b13f22b6bfba6b96c553d89287e203328fab5aaba6b04502a1ad5dba319f8e
-  data.tar.gz: a723d906fe86668fa7f19c44f86222d79fff8b6b934ea13832950045c2c64a0a
+  metadata.gz: a78ffff1b9845b058f35013adea659ae8a8b03f21c522494122255f1774f0913
+  data.tar.gz: 4411573fb6ebf9808efdf42d0d4be6496cdd18f07a9c637d326075a5314c2f14
 SHA512:
-  metadata.gz: eab209704e695bc8f124fd096acf0b5e39b50a952d8c137d4b6399925c09e9817dd5bdf67e1c5fcd2d6e56516b7c9b5c2a6c9dc9da122689c4ee0dea0f350f83
-  data.tar.gz: 2cc5cc8622f06648161a72fa5abb35924cc030a9f334ba69cebecb5a2e59c93a52d749fcc6fc1eb2101c5c421bcac52b298a6b6a686d85c821661042fdecbf2b
+  metadata.gz: c9aa86d8864d7204613bf89db1f78811b944d7cbe842f2f5e6c4bd95448bbb500bcfcd201c6e5519532a85fa9acf3974592f642651f793fd7317db80f38823df
+  data.tar.gz: e07bd405386de50eb128ab77984ae8eb47786f80c180fa3a8e8e8ba76503e8d3bbb306906eb9cffb25166ffbb9fb30cd06a9296c4581d606792a49d8f89bd130

data/CHANGELOG.md

@@ -30,6 +30,23 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.1.4] - 2026-09-14
+
+- TAG: [v0.1.4][0.1.4t]
+- COVERAGE: 94.54% -- 848/897 lines in 15 files
+- BRANCH COVERAGE: 78.67% -- 225/286 branches in 15 files
+- 91.86% documented
+
+### Added
+
+- Generate `gemfiles/modular/activerecord_support.gemfile` (sqlite3 1.4.x) and `activerecord_support_modern.gemfile` (sqlite3 >= 2.1) with JRuby JDBC adapter blocks when `activerecord` is a tier1 gem, and wire the matching one into each generated appraisal by ActiveRecord version; opt out with `appraisal_matrix.activerecord_support: false`.
+- Document collapsing onto standard `ruby-X-Y` appraisals (intentional duplicate avoidance), collapse policies, and shared `appraisal_gemfiles`.
+
+### Fixed
+
+- Read and write `appraisal_matrix` in `.structuredmerge/kettle-jem.yml` (the file kettle-jem uses), falling back to a legacy root `.kettle-jem.yml`.
+- Preserve comments and all other settings when writing the config; only changed top-level sections are rewritten.
+
 ## [0.1.3] - 2026-09-11
 
 - TAG: [v0.1.3][0.1.3t]
@@ -177,7 +194,9 @@ 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.3...HEAD
+[Unreleased]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.4...HEAD
+[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
 [0.1.3t]: https://github.com/appraisal-rb/kettle-jem-appraisals/releases/tag/v0.1.3
 [0.1.2]: https://github.com/appraisal-rb/kettle-jem-appraisals/compare/v0.1.1...v0.1.2

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 `.kettle-jem.yml` and
+This test floor is configured by `ruby.test_minimum` in `.structuredmerge/kettle-jem.yml` and
 may be higher than the gem's runtime compatibility floor when legacy Rubies are
 not practical for the current toolchain.
 
@@ -144,8 +144,16 @@ gem install kettle-jem-appraisals
 
 ## ⚙️ Configuration
 
-Configuration lives in `.kettle-jem.yml` under the `appraisal_matrix` key.
-Running `--scaffold` creates a starter config from your gemspec.
+Configuration lives under the `appraisal_matrix` key of the project's
+[kettle-jem](https://github.com/kettle-dev/kettle-jem) configuration file,
+`.structuredmerge/kettle-jem.yml` — the same file kettle-jem reads when templating.
+Projects that still have a legacy root `.kettle-jem.yml` (and no
+`.structuredmerge/kettle-jem.yml`) are read from there instead.
+Running `--scaffold` creates a starter `appraisal_matrix` from your gemspec.
+
+Writes are surgical: `--scaffold` and `--resolve` only rewrite the top-level
+sections they change (normally just `appraisal_matrix`), so comments and every
+other kettle-jem setting in the file are preserved.
 
 ### Config schema
 
@@ -162,6 +170,19 @@ appraisal_matrix:
   # Command to run in CI for each appraisal entry (default: "rake spec")
   exec_cmd: "rake spec"
 
+  # How generated entries collapse onto kettle-jem's standard ruby-X-Y
+  # appraisals (default: unique). See "Collapsing onto standard appraisals".
+  standard_appraisal_role: runtime_dependency
+
+  # Shared support gemfiles evaluated by every generated entry (and injected
+  # by kettle-jem into standard test appraisals). See "Shared support gemfiles".
+  appraisal_gemfiles:
+    - modular/combustion.gemfile
+
+  # Generate and wire ActiveRecord database support gemfiles when activerecord
+  # is a tier1 gem (default: true). See "ActiveRecord database support".
+  activerecord_support: true
+
   gems:
     # Tier 1: primary dependencies whose versions drive the matrix.
     # Each tier1 version is assigned to its optimal Ruby bucket.
@@ -311,6 +332,82 @@ Common gem abbreviations are applied automatically:
 
 Examples: `kja-ar-7-1-oa-2-1-r3`, `kja-mail-2-8-r3` (tier1-only)
 
+#### Collapsing onto standard appraisals
+
+kettle-jem already generates one standard appraisal per supported Ruby series
+(`ruby-2-7`, `ruby-3-1`, …), and each of those already has a CI job. A generated
+`kja-*` entry whose Ruby bucket maps to one of those series would otherwise be a
+**duplicate** appraisal (and duplicate CI job) for the same Ruby. To avoid that,
+kettle-jem-appraisals intentionally **collapses** one generated entry per
+standard series onto the standard name: the entry keeps its `kja-*` name
+internally, but is emitted as `appraise "ruby-X-Y"`. kettle-jem then merges that
+block with its own templated `ruby-X-Y` block, so the standard job runs against
+the generated dependency versions. Every entry that is not collapsed keeps its
+`kja-*` name, and stale-file cleanup still keys off the `kja-` prefix.
+
+Which entry collapses is controlled by the collapse policy, read from
+`appraisal_matrix.collapse.standard_appraisals`, `standard_appraisal_role`, or
+`standard_appraisal_collapse` (first one set wins):
+
+| Policy                  | Accepted values                                              | Behavior                                                                                                                    |
+|-------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
+| **unique** (default)    | anything not listed below                                    | Collapse only when a single generated entry maps to the series; ambiguous series keep all entries as `kja-*`.            |
+| **required**            | `required`, `runtime`, `runtime_dependency`, `dependency`, `substrate` | Always collapse one entry per series — the one with the highest tier1 (then tier2) version. Use when the tier1 gem is a runtime dependency every standard job needs. |
+| **none**                | `none`, `false`, `off`, `no`, `never`                        | Never collapse; every entry stays `kja-*`.                                                                                  |
+
+For example, with `standard_appraisal_role: runtime_dependency` and an
+`activerecord` tier1, the `r3.1` bucket's ActiveRecord 7.2 entry is emitted as
+`ruby-3-1`, while an extra ActiveRecord 7.0 entry for the same bucket stays
+`kja-ar-7-0-r2`.
+
+### Shared support gemfiles
+
+`appraisal_matrix.appraisal_gemfiles` (alias: `appraisal_eval_gemfiles`) lists
+modular gemfiles that every generated entry should `eval_gemfile`, such as
+test-only fixtures (`modular/combustion.gemfile`). Paths may be given with or
+without the leading `gemfiles/`. kettle-jem reads the same key (or
+`workflows.standard_appraisal_gemfiles`) to inject those gemfiles into its
+standard test appraisals, so collapsed and non-collapsed jobs share them.
+
+kettle-jem's `test_bundle.gemfiles` is separate: it controls the root
+`Gemfile` used for local development and the locked-deps workflow, and is not
+changed by `appraisal_matrix`.
+
+### ActiveRecord database support
+
+This gem's primary use case is gems that are tested against a spread of
+ActiveRecord versions on MRI, JRuby, and TruffleRuby. Those test suites need a
+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
+  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).
+
+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
+via kettle-jem's `test_bundle.gemfiles`, and select the JDBC adapter in your spec
+helper on JRuby:
+
+```ruby
+require "active_record"
+if RUBY_PLATFORM == "java"
+  require "activerecord-jdbcsqlite3-adapter"
+else
+  require "sqlite3"
+end
+adapter = (RUBY_PLATFORM == "java" && ActiveRecord.version < Gem::Version.new("7.2")) ? "jdbcsqlite3" : "sqlite3"
+ActiveRecord::Base.establish_connection(adapter: adapter, database: ":memory:")
+```
+
 ### Optimal bucket assignment
 
 Rather than cross-producting every gem version with every Ruby series,
@@ -331,7 +428,7 @@ Example with `activerecord`:
 
 ### Two-step workflow
 
-**Step 1 — Scaffold** reads your gemspec and populates `.kettle-jem.yml`:
+**Step 1 — Scaffold** reads your gemspec and populates `appraisal_matrix` in `.structuredmerge/kettle-jem.yml`:
 
 ```sh
 kettle-jem-appraisals --scaffold
@@ -659,7 +756,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.786-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.897-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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Kettle
+  module Jem
+    module Appraisals
+      # Generates the modular gemfiles that give ActiveRecord test suites a
+      # 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 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.
+      #
+      # Files that exist without the {GENERATED_HEADER} are treated as
+      # hand-maintained and are never overwritten.
+      #
+      # @example
+      #   generator = ActiveRecordSupportGemfileGenerator.new(base_dir: "/path/to/gem")
+      #   generator.generate
+      #   generator.eval_path_for("7.1.6") #=> "modular/activerecord_support.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 [Gem::Version] first ActiveRecord release that supports sqlite3 2.x
+        MODERN_ACTIVERECORD = Gem::Version.new("7.2")
+
+        # @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
+
+        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
+          def support_gemfile?(path)
+            normalized = path.to_s.strip.sub(%r{\Agemfiles/}, "")
+            VARIANTS.keys.any? { |variant| variant.delete_prefix("gemfiles/") == normalized }
+          end
+        end
+
+        # @return [String] absolute path to the project root
+        attr_reader :base_dir
+
+        # @param base_dir [String] path to the project root
+        def initialize(base_dir: Dir.pwd)
+          @base_dir = base_dir
+        end
+
+        # Writes both support gemfiles, skipping any hand-maintained file.
+        #
+        # @return [Hash{String => Symbol}] relative path => +:written+ or +:kept+
+        def generate
+          VARIANTS.each_with_object({}) do |(relative_path, variant), results|
+            absolute = File.join(base_dir, relative_path)
+            if File.exist?(absolute) && !File.read(absolute).include?(GENERATED_HEADER)
+              results[relative_path] = :kept
+              next
+            end
+
+            FileUtils.mkdir_p(File.dirname(absolute))
+            File.write(absolute, build_content(variant))
+            results[relative_path] = :written
+          end
+        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/")
+        end
+
+        private
+
+        def build_content(variant)
+          sqlite3 = [%("sqlite3"), *variant.fetch(:sqlite3).map(&:inspect), "platforms: [:ruby]"].join(", ")
+          <<~GEMFILE
+            # frozen_string_literal: true
+
+            #{GENERATED_HEADER}
+            # Database drivers for #{variant.fetch(:label)}: sqlite3 on MRI/TruffleRuby,
+            # activerecord-jdbcsqlite3-adapter on JRuby (its release series tracks ActiveRecord).
+            gem #{sqlite3}
+
+            platforms :jruby do
+              gem "activerecord-jdbcsqlite3-adapter", ">= 1.3"
+              gem "bigdecimal", ">= 1"
+            end
+          GEMFILE
+        end
+      end
+    end
+  end
+end

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

@@ -13,7 +13,7 @@ module Kettle
       # or accepts explicit +--scaffold+ / +--resolve+ flags.
       #
       # In *scaffold* mode, reads the project gemspec, excludes standard-library
-      # gems, and writes a skeleton +.kettle-jem.yml+ with tier1 candidates.
+      # gems, and writes a skeleton +appraisal_matrix+ into +.structuredmerge/kettle-jem.yml+ with tier1 candidates.
       #
       # In *resolve* mode, queries RubyGems for version data, assigns gem
       # versions to Ruby-series buckets, generates modular gemfiles, an
@@ -26,8 +26,11 @@ module Kettle
       #   cli = Kettle::Jem::Appraisals::CLI.new(["--scaffold"], project_dir: "/path/to/gem")
       #   cli.run
       class CLI
-        # @return [String] name of the per-project YAML configuration file
-        CONFIG_FILE = ".kettle-jem.yml"
+        # @return [String] canonical per-project kettle-jem configuration file (holds +appraisal_matrix+)
+        CONFIG_FILE = Kettle::Jem::KETTLE_CONFIG_PATH
+
+        # @return [String] legacy per-project configuration file, read when {CONFIG_FILE} is absent
+        LEGACY_CONFIG_FILE = Kettle::Jem::LEGACY_KETTLE_CONFIG_PATH
 
         # @return [String] top-level key in the YAML config that holds the appraisal matrix
         APPRAISAL_MATRIX_KEY = "appraisal_matrix"
@@ -125,10 +128,10 @@ module Kettle
           config[APPRAISAL_MATRIX_KEY] = matrix
           write_config(config)
 
-          puts "  ✅ Wrote scaffold to #{CONFIG_FILE}"
+          puts "  ✅ Wrote scaffold to #{config_file.relative_path}"
           puts ""
           puts "  Next steps:"
-          puts "  1. Edit #{CONFIG_FILE} — arrange gems into tier1 and tier2"
+          puts "  1. Edit #{config_file.relative_path} — arrange gems into tier1 and tier2"
           puts "  2. Run `kettle-jem-appraisals` again (or `--resolve`) to generate matrix"
         end
 
@@ -140,7 +143,7 @@ module Kettle
           config = load_config
           matrix = config[APPRAISAL_MATRIX_KEY]
           unless matrix
-            warn "  ❌ No #{APPRAISAL_MATRIX_KEY} in #{CONFIG_FILE}. Run --scaffold first."
+            warn "  ❌ No #{APPRAISAL_MATRIX_KEY} in #{config_file.relative_path}. Run --scaffold first."
             exit(1)
           end
 
@@ -263,6 +266,7 @@ module Kettle
             sub_resolver
           )
           annotate_extra_gemfiles(appraisal_entries, matrix_extra_gemfiles(matrix))
+          annotate_activerecord_support(appraisal_entries, tier1_gems, matrix)
           annotate_standard_appraisal_collapses(appraisal_entries, bucket_ranges, matrix)
 
           puts "  📊 Generated #{appraisal_entries.size} appraisal entries"
@@ -323,16 +327,16 @@ module Kettle
           puts "  🗑️  Removed #{stale.size} stale gemfile(s)"
         end
 
-        def load_config
-          path = File.join(project_dir, CONFIG_FILE)
-          return {} unless File.exist?(path)
+        def config_file
+          @config_file ||= ConfigFile.new(project_dir: project_dir)
+        end
 
-          YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+        def load_config
+          config_file.load
         end
 
         def write_config(config)
-          path = File.join(project_dir, CONFIG_FILE)
-          File.write(path, YAML.dump(config))
+          config_file.write(config)
         end
 
         def find_gemspec
@@ -437,6 +441,7 @@ module Kettle
 
                 entries << {
                   name: GemAbbreviations.appraisal_name(t1_name, t1_ver, nil, nil, rs),
+                  tier1_name: t1_name,
                   tier1_version: t1_ver,
                   tier1_gemfile: t1_gemfile,
                   tier2_gemfile: nil,
@@ -479,6 +484,8 @@ module Kettle
 
                     entries << {
                       name: GemAbbreviations.appraisal_name(t1_name, t1_ver, t2_name, t2_ver, rs),
+                      tier1_name: t1_name,
+                      tier2_name: t2_name,
                       tier1_version: t1_ver,
                       tier2_version: t2_ver,
                       tier1_gemfile: t1_gemfile,
@@ -591,7 +598,7 @@ module Kettle
           return if extra_gemfiles.empty?
 
           appraisal_entries.each do |entry|
-            entry[:extra_gemfiles] = extra_gemfiles
+            entry[:extra_gemfiles] = (Array(entry[:extra_gemfiles]) + extra_gemfiles).uniq
           end
         end
 
@@ -602,6 +609,34 @@ 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.
+        # 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)
+          return unless activerecord_support_enabled?(matrix)
+          return unless tier1_gems.any? { |gem_config| gem_config["name"] == "activerecord" }
+          return if matrix_extra_gemfiles(matrix).any? { |path| ActiveRecordSupportGemfileGenerator.support_gemfile?(path) }
+
+          generator = ActiveRecordSupportGemfileGenerator.new(base_dir: project_dir)
+          generator.generate.each do |path, status|
+            puts "  🗄️  #{(status == :written) ? "Wrote" : "Kept hand-maintained"} #{path}"
+          end
+          appraisal_entries.each do |entry|
+            next unless entry[:tier1_name] == "activerecord" && entry[:tier1_version]
+
+            support = generator.eval_path_for(entry[:tier1_version])
+            entry[:extra_gemfiles] = [support, *Array(entry[:extra_gemfiles])].uniq
+          end
+        end
+
+        def activerecord_support_enabled?(matrix)
+          value = matrix.is_a?(Hash) ? matrix["activerecord_support"] : nil
+          return true if value.nil?
+
+          !%w[false no off none never 0].include?(value.to_s.strip.downcase)
+        end
+
         def annotate_standard_appraisal_collapses(appraisal_entries, bucket_ranges, matrix = {})
           policy = standard_appraisal_collapse_policy(matrix)
           by_standard = appraisal_entries.group_by do |entry|

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module Kettle
+  module Jem
+    module Appraisals
+      # Reads and surgically updates the project's kettle-jem configuration file.
+      #
+      # The +appraisal_matrix+ lives in the same file kettle-jem uses
+      # (+.structuredmerge/kettle-jem.yml+). That file is heavily commented and
+      # holds many other settings, so writes only replace the top-level sections
+      # whose values changed, leaving comments and every other section intact.
+      #
+      # @example
+      #   config_file = ConfigFile.new(project_dir: "/path/to/gem")
+      #   config = config_file.load
+      #   config["appraisal_matrix"]["resolved_at"] = Time.now.to_i
+      #   config_file.write(config)
+      class ConfigFile
+        # @return [String] canonical config path, relative to the project root
+        CANONICAL_PATH = Kettle::Jem::KETTLE_CONFIG_PATH
+
+        # @return [String] legacy config path, read only when the canonical file is absent
+        LEGACY_PATH = Kettle::Jem::LEGACY_KETTLE_CONFIG_PATH
+
+        # @return [String] absolute path to the project root
+        attr_reader :project_dir
+
+        # @param project_dir [String] path to the project root
+        def initialize(project_dir:)
+          @project_dir = project_dir
+        end
+
+        # The config file to read and write: the canonical file when present,
+        # otherwise an existing legacy file, otherwise the canonical location.
+        #
+        # @return [String] absolute path
+        def path
+          canonical = File.join(project_dir, CANONICAL_PATH)
+          return canonical if File.exist?(canonical)
+
+          legacy = File.join(project_dir, LEGACY_PATH)
+          return legacy if File.exist?(legacy)
+
+          canonical
+        end
+
+        # @return [String] {#path} relative to the project root, for messages
+        def relative_path
+          File.expand_path(path).delete_prefix("#{File.expand_path(project_dir)}/")
+        end
+
+        # @return [Hash] the parsed config, or an empty Hash when the file does not exist
+        def load
+          return {} unless File.exist?(path)
+
+          YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+        end
+
+        # Writes +config+, replacing only the top-level sections that differ from
+        # the file on disk. Creates the file (and its directory) when missing.
+        #
+        # @param config [Hash] the full desired config
+        # @return [void]
+        def write(config)
+          target = path
+          unless File.exist?(target)
+            FileUtils.mkdir_p(File.dirname(target))
+            File.write(target, YAML.dump(config))
+            return
+          end
+
+          content = File.read(target)
+          current = YAML.safe_load(content, permitted_classes: [Symbol]) || {}
+          config.each do |key, value|
+            next if current.key?(key) && current[key] == value
+
+            content = upsert_section(content, key.to_s, value)
+          end
+          File.write(target, content)
+        end
+
+        private
+
+        def upsert_section(content, key, value)
+          block = YAML.dump({key => value}).delete_prefix("---\n")
+          range = section_range(content, key)
+          return "#{content.rstrip}\n\n#{block}" unless range
+
+          lines = content.lines
+          [*lines[0...range.begin], block, *lines[range.end..]].join
+        end
+
+        # Line range (0-based, end-exclusive) of the top-level +key+ section.
+        # A parsed section runs up to the next top-level key, so trailing blank
+        # lines and comment lines (commented-out settings, or comments that
+        # introduce the next section) are trimmed back out of the range and kept.
+        def section_range(content, key)
+          require "yaml/merge"
+
+          analysis = Yaml::Merge::FileAnalysis.new(content)
+          raise ArgumentError, "could not parse #{relative_path} as YAML" unless analysis.valid?
+
+          body = analysis.documents.first&.body_node
+          return unless body&.mapping?
+
+          lines = content.lines
+          pairs = body.mapping_pairs
+          pairs.each_with_index do |pair, index|
+            next unless pair.key_name == key
+
+            start_index = pair.start_line.to_i - 1
+            next_pair = pairs[index + 1]
+            end_index = next_pair ? next_pair.start_line.to_i - 1 : lines.length
+            end_index -= 1 while end_index > start_index + 1 && trailing_trivia?(lines[end_index - 1])
+            return start_index...end_index
+          end
+
+          nil
+        end
+
+        # @return [Boolean] whether +line+ is blank or a comment (at any indentation)
+        def trailing_trivia?(line)
+          stripped = line.strip
+          stripped.empty? || stripped.start_with?("#")
+        end
+      end
+    end
+  end
+end

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.3"
+        VERSION = "0.1.4"
       end
       # Current gem version exposed at the traditional constant location.
       VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/jem/appraisals.rb

@@ -15,7 +15,9 @@ module Kettle
         path.to_s.sub(VAR_HOME_PREFIX, "/home")
       end
 
+      autoload :ActiveRecordSupportGemfileGenerator, "kettle/jem/appraisals/active_record_support_gemfile_generator"
       autoload :CLI, "kettle/jem/appraisals/cli"
+      autoload :ConfigFile, "kettle/jem/appraisals/config_file"
       autoload :GemAbbreviations, "kettle/jem/appraisals/gem_abbreviations"
       autoload :GemVersionResolver, "kettle/jem/appraisals/gem_version_resolver"
       autoload :MatrixBuilder, "kettle/jem/appraisals/matrix_builder"

data/sig/kettle/jem/appraisals.rbs

@@ -10,8 +10,47 @@ module Kettle
         def self.generate: (Array[Hash[Symbol, untyped]] matrix) -> String
       end
 
+      class ActiveRecordSupportGemfileGenerator
+        GENERATED_HEADER: String
+        LEGACY_PATH: String
+        MODERN_PATH: String
+        MODERN_ACTIVERECORD: Gem::Version
+        VARIANTS: Hash[String, Hash[Symbol, untyped]]
+
+        attr_reader base_dir: String
+
+        def self.support_gemfile?: (String path) -> bool
+        def initialize: (?base_dir: String) -> void
+        def generate: () -> Hash[String, Symbol]
+        def eval_path_for: (String | Gem::Version activerecord_version) -> String
+
+        private
+
+        def build_content: (Hash[Symbol, untyped] variant) -> String
+      end
+
+      class ConfigFile
+        CANONICAL_PATH: String
+        LEGACY_PATH: String
+
+        attr_reader project_dir: String
+
+        def initialize: (project_dir: String) -> void
+        def path: () -> String
+        def relative_path: () -> String
+        def load: () -> Hash[String, untyped]
+        def write: (Hash[String, untyped] config) -> void
+
+        private
+
+        def upsert_section: (String content, String key, untyped value) -> String
+        def section_range: (String content, String key) -> Range[Integer]?
+        def trailing_trivia?: (String line) -> bool
+      end
+
       class CLI
         CONFIG_FILE: String
+        LEGACY_CONFIG_FILE: String
         APPRAISAL_MATRIX_KEY: String
         DEFAULT_FRESHNESS_TTL: Integer
 
@@ -28,8 +67,12 @@ module Kettle
         def has_versions?: (Hash[String, untyped] matrix) -> bool
         def run_scaffold: () -> void
         def run_resolve: () -> void
+        def config_file: () -> ConfigFile
         def load_config: () -> Hash[String, untyped]
         def write_config: (Hash[String, untyped] config) -> void
+        def annotate_extra_gemfiles: (Array[Hash[Symbol, untyped]] appraisal_entries, Array[String] extra_gemfiles) -> void
+        def annotate_activerecord_support: (Array[Hash[Symbol, untyped]] appraisal_entries, Array[Hash[String, untyped]] tier1_gems, Hash[String, untyped] matrix) -> void
+        def activerecord_support_enabled?: (Hash[String, untyped]? matrix) -> bool
         def find_gemspec: () -> String?
         def extract_runtime_deps: (String gemspec_path) -> Array[String]
         def fresh?: (Hash[String, untyped] matrix) -> bool

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-jem-appraisals
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Peter H. Boling
@@ -296,8 +296,10 @@ files:
 - exe/kettle-jem-appraisals
 - lib/kettle-jem-appraisals.rb
 - lib/kettle/jem/appraisals.rb
+- lib/kettle/jem/appraisals/active_record_support_gemfile_generator.rb
 - lib/kettle/jem/appraisals/appraisals_generator.rb
 - lib/kettle/jem/appraisals/cli.rb
+- lib/kettle/jem/appraisals/config_file.rb
 - lib/kettle/jem/appraisals/gem_abbreviations.rb
 - lib/kettle/jem/appraisals/gem_version_resolver.rb
 - lib/kettle/jem/appraisals/matrix_builder.rb
@@ -313,10 +315,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.3
-  changelog_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/blob/v0.1.3/CHANGELOG.md
+  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
   bug_tracker_uri: https://github.com/appraisal-rb/kettle-jem-appraisals/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-jem-appraisals/0.1.3
+  documentation_uri: https://www.rubydoc.info/gems/kettle-jem-appraisals/0.1.4
   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