appraisal2 3.0.9 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a27b04028f7284aace3c5b46e35cbbdd3279d7d493c1e6b95a8839931a98ae24
-  data.tar.gz: 1a3f7d92cb6c41c9112cd037add5806bdfa7b4bab2576a95847b0e3c5395db2c
+  metadata.gz: 2c2316bffba1559cb55b0c393052bd487630867af9e7a41d37c73c43315bc2b9
+  data.tar.gz: a37397565aa148f422d031621cb715d2b48bffcd3f9ddba06aa773488f984995
 SHA512:
-  metadata.gz: 78978be68901ed5a57ebbfbafeece3752834caedb337cb5e30a5d60eed5a8d89ea23ab5b1930746b5e0d59fd93487878ae5f0bee312fb30c6247bcf65f5e37e8
-  data.tar.gz: 9828a29976bf915e45e23c5a13275efe1b2124ed4556bcff50e90922cde411ce85f3d46f7a3739c5433fe1387b40e028debd1a3918e1dd2944c2b90c63fc2180
+  metadata.gz: f9a4fe27e3fb3e5979021df8b565f32ad454c924f2aaa1a15d0517d66b5fa2fd095c2daaae9cf0d422f4445510d44f6e0604d0acd735d3131189d7c54ab79ca9
+  data.tar.gz: 1415ef332fc92e289a1f28fe4b9cfcd401d5699e2556d1bacfb463e67420121fd45b6184fca10c6b88a445c83f59c5e573b4bab5b047bd8707d2667046448a15

data/CHANGELOG.md

@@ -30,6 +30,51 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.1.1] - 2026-06-06
+
+- TAG: [v3.1.1][3.1.1t]
+- COVERAGE: 90.23% -- 822/911 lines in 29 files
+- BRANCH COVERAGE: 80.51% -- 157/195 branches in 29 files
+- 42.25% documented
+
+### Added
+
+- Added the `plugin` Appraisals DSL for generator-only companion gems that
+  should be loaded while Appraisal2 generates gemfiles without being serialized
+  into generated appraisal gemfiles.
+- Added the `generator_only` root Gemfile DSL for dependencies that Bundler
+  should install in the active generator bundle but Appraisal2 should not
+  serialize into generated appraisal gemfiles.
+
+## [3.1.0] - 2026-06-06
+
+- TAG: [v3.1.0][3.1.0t]
+- COVERAGE: 90.14% -- 814/903 lines in 29 files
+- BRANCH COVERAGE: 80.00% -- 148/185 branches in 29 files
+- 42.70% documented
+
+### Added
+
+- Added Appraisal lifecycle hooks, including `Appraisal.transform_gemfile`
+  for plugins that need to normalize generated Appraisal gemfiles in memory
+  before Appraisal2 writes them.
+- Added explicit `generate-install` and `generate-update` CLI commands for
+  workflows that need to regenerate Appraisal gemfiles before resolving them.
+- Added named appraisal support for `generate`, `generate-install`, and
+  `generate-update`.
+
+### Changed
+
+- Changed `install` and `update` to resolve existing Appraisal gemfiles without
+  rewriting them, while still generating missing Appraisal gemfiles to preserve
+  the basic install workflow.
+- Updated the deprecated `rake appraisal:install` task to delegate to
+  `appraisal generate-install`, preserving its historical generate-and-install
+  behavior.
+
+- Documented the Appraisal2 3.1.0 command lifecycle changes, named appraisal
+  generation commands, and generated gemfile transform hooks in the README.
+
 ## [3.0.9] - 2026-06-05
 
 - TAG: [v3.0.9][3.0.9t]
@@ -316,7 +361,11 @@ Please file a bug if you notice a violation of semantic versioning.
   - code coverage tracked with Coveralls, QLTY.sh, and the kettle-soup-cover gem
   - other minor fixes and improvements
 
-[Unreleased]: https://github.com/appraisal-rb/appraisal2/compare/v3.0.9...HEAD
+[Unreleased]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.1...HEAD
+[3.1.1]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.0...v3.1.1
+[3.1.1t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.1.1
+[3.1.0]: https://github.com/appraisal-rb/appraisal2/compare/v3.0.9...v3.1.0
+[3.1.0t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.1.0
 [3.0.9]: https://github.com/appraisal-rb/appraisal2/compare/v3.0.8...v3.0.9
 [3.0.9t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.0.9
 [3.0.8]: https://github.com/appraisal-rb/appraisal2/compare/v3.0.7...v3.0.8

data/README.md

@@ -34,6 +34,14 @@ and [Joe Ferris](https://github.com/jferris), the original author!
 Appraisal2 adds:
 
 - support for `eval_gemfile`
+- explicit `generate`, `install`, and `update` workflows, so CI can resolve
+  already-generated appraisal gemfiles without rewriting them
+- `generate-install` and `generate-update` commands for workflows that need to
+  regenerate appraisal gemfiles before resolving dependencies
+- named appraisal support for `generate`, `generate-install`, and
+  `generate-update`
+- lifecycle hooks, including `Appraisal.transform_gemfile`, for plugins that
+  need to normalize generated appraisal gemfiles before Appraisal2 writes them
 - support for caching gems across appraisals in CI workflows by setting `BUNDLE_PATH` in env
 - support for [ORE](https://github.com/contriboss/ore-light) as an alternative gem manager (faster than bundler!)
   - For easy setup in **Gitea** [Actions](https://docs.gitea.com/usage/actions/overview), **Forgejo** [Actions](https://forgejo.org/docs/next/admin/actions/), **Codeberg** [Actions](https://docs.codeberg.org/ci/actions/), or **GitHub** [Actions](https://github.com/marketplace/actions/setup-ruby-with-rv-and-ore) check out [appraisal-rb/setup-ruby-flash](https://github.com/appraisal-rb/setup-ruby-flash)
@@ -53,7 +61,7 @@ Appraisal2 adds:
 | Works with Truffle Ruby | [![Truffle Ruby 22.3 Compat][💎truby-22.3i]][🚎truby-22.3-wf] [![Truffle Ruby 23.0 Compat][💎truby-23.0i]][🚎truby-23.0-wf] [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎truby-23.1-wf] <br/> [![Truffle Ruby 24.2 Compat][💎truby-24.2i]][🚎truby-24.2-wf] [![Truffle Ruby 25.0 Compat][💎truby-25.0i]][🚎truby-25.0-wf] [![Truffle Ruby current Compat][💎truby-c-i]][🚎9-t-wf]|
 | Works with MRI Ruby 4 | [![Ruby 4.0 Compat][💎ruby-4.0i]][🚎11-c-wf] [![Ruby current Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]|
 | Works with MRI Ruby 3 | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎ruby-3.0-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎ruby-3.1-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎ruby-3.2-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎ruby-3.3-wf] [![Ruby 3.4 Compat][💎ruby-3.4i]][🚎ruby-3.4-wf]|
-| Works with MRI Ruby 2 | ![Ruby 2.0 Compat][💎ruby-2.0i] ![Ruby 2.1 Compat][💎ruby-2.1i] ![Ruby 2.2 Compat][💎ruby-2.2i] <br/> [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎ruby-2.4-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎ruby-2.5-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎ruby-2.6-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎ruby-2.7-wf]|
+| Works with MRI Ruby 2 | ![Ruby 2.0 Compat][💎ruby-2.0i] ![Ruby 2.1 Compat][💎ruby-2.1i] ![Ruby 2.2 Compat][💎ruby-2.2i] ![Ruby 2.3 Compat][💎ruby-2.3i] <br/> [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎ruby-2.4-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎ruby-2.5-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎ruby-2.6-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎ruby-2.7-wf]|
 | Works with MRI Ruby 1 | ![Ruby 1.9 Compat][💎ruby-1.9i]|
 | Support & Community | [![Join Me on Daily.dev's RubyFriends][✉️ruby-friends-img]][✉️ruby-friends] [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor] |
 | Source | [![Source on GitLab.com][📜src-gl-img]][📜src-gl] [![Source on CodeBerg.org][📜src-cb-img]][📜src-cb] [![Source on Github.com][📜src-gh-img]][📜src-gh] [![The best SHA: dQw4w9WgXcQ!][🧮kloc-img]][🧮kloc] |
@@ -130,6 +138,87 @@ gem install appraisal2
 
 ## ⚙️ Configuration
 
+Create an `Appraisals` file at the root of your project, then define one or
+more dependency scenarios:
+
+```ruby
+appraise "rails-7" do
+  gem "rails", "~> 7.0"
+end
+
+appraise "rails-8" do
+  gem "rails", "~> 8.0"
+end
+```
+
+Each appraisal starts from your root `Gemfile`, then applies the dependency
+changes declared in the matching `appraise` block. Generated appraisal gemfiles
+are written to `gemfiles/*.gemfile`.
+
+### Generated Gemfile Hooks
+
+Appraisal2 3.1.0 adds lifecycle hooks for companion gems and local tooling.
+The primary hook is `Appraisal.transform_gemfile`, which receives generated
+gemfile content before Appraisal2 writes it.
+
+```ruby
+Appraisal.transform_gemfile do |content, context|
+  # context.appraisal is the Appraisal::Appraisal instance.
+  # context.path is the generated gemfile path.
+  content.gsub(%(source "https://rubygems.org"), %(source "https://gem.coop"))
+end
+```
+
+Hooks run in memory. Appraisal2 writes the final transformed content once, after
+all registered transforms have run. A transform may accept only `content`, or it
+may accept `content, context`. Returning `nil` leaves the current content
+unchanged.
+
+This is intended for plugin gems that need deterministic generated output, such
+as style normalization of appraisal gemfiles, without monkey-patching Appraisal2
+internals.
+
+### Generator Plugins
+
+Use `plugin` in `Appraisals` for companion gems that must be loaded while
+Appraisal2 evaluates and generates appraisal gemfiles, but must not be written
+as dependencies in the generated appraisal gemfiles.
+
+```ruby
+plugin "appraisal2-rubocop",
+  :require => "appraisal2/rubocop",
+  :optional => true
+```
+
+`plugin` requires the requested path in the active generator bundle. It does not
+call `gem`, and it is not serialized into `gemfiles/*.gemfile`. This keeps
+generator-only tooling out of appraisals that target older Rubies, while still
+allowing modern generator workflows to load hooks such as
+`Appraisal.transform_gemfile`.
+
+Set `:optional => true` when some workflows evaluate `Appraisals` without the
+plugin dependency installed. This is useful when a CI matrix uses one generator
+bundle for old-Ruby appraisals and another modern workflow provides the plugin.
+
+If the generator bundle needs dependencies that must not be copied into every
+generated appraisal gemfile, wrap those root Gemfile declarations with
+`generator_only` for Appraisal2 and leave the Bundler branch unchanged:
+
+```ruby
+if respond_to?(:generator_only)
+  generator_only do
+    eval_gemfile "gemfiles/modular/style.gemfile"
+  end
+else
+  eval_gemfile "gemfiles/modular/style.gemfile"
+end
+```
+
+Bundler evaluates the `else` branch while installing the active generator
+bundle. Appraisal2 evaluates the `generator_only` branch while parsing the root
+Gemfile, but intentionally does not serialize that block into generated
+appraisal gemfiles.
+
 ## 🔧 Basic Usage
 
 Once you've configured the appraisals you want to use, you need to install the
@@ -137,9 +226,17 @@ dependencies for each appraisal:
 
     $ bundle exec appraisal install
 
-This will resolve, install, and lock the dependencies for that appraisal using
-bundler. Once you have your dependencies set up, you can run any command in a
-single appraisal:
+This resolves, installs, and locks dependencies for each generated appraisal
+gemfile using bundler. If an appraisal gemfile is missing, `install` generates
+that missing gemfile first, preserving the basic setup workflow.
+
+When you intentionally want to regenerate every appraisal gemfile before
+installing dependencies, use:
+
+    $ bundle exec appraisal generate-install
+
+Once you have your dependencies set up, you can run any command in a single
+appraisal:
 
     $ bundle exec appraisal rails-3 rake test
 
@@ -173,40 +270,65 @@ default.
 ```bash
 appraisal clean                  # Remove all generated gemfiles and lockfiles from gemfiles folder
 appraisal generate               # Generate a gemfile for each appraisal
+appraisal generate-install       # Generate gemfiles, then resolve and install dependencies
+appraisal generate-update [LIST_OF_GEMS] # Generate gemfiles, then update dependencies
 appraisal help [COMMAND]         # Describe available commands or one specific command
-appraisal install                # Resolve and install dependencies for each appraisal
+appraisal install                # Resolve and install dependencies for each generated appraisal gemfile
 appraisal list                   # List the names of the defined appraisals
-appraisal update [LIST_OF_GEMS]  # Remove all generated gemfiles and lockfiles, resolve, and install dependencies again
+appraisal update [LIST_OF_GEMS]  # Update dependencies for each generated appraisal gemfile
 appraisal version                # Display the version and exit
 ```
 
+Since Appraisal2 3.1.0, `install` and `update` do not rewrite existing appraisal
+gemfiles. They operate on the generated files already present under `gemfiles/`.
+This matters in CI and plugin workflows where generated gemfiles may be
+normalized by hooks or committed as stable inputs.
+
+Use the command that matches the lifecycle you want:
+
+| Command | Regenerates appraisal gemfiles? | Resolves dependencies? | Typical use |
+|---------|---------------------------------|-------------------------|-------------|
+| `generate` | Yes | No | Refresh generated gemfiles after editing `Appraisals` |
+| `install` | Only missing gemfiles | Yes, via install | CI or local setup using existing generated gemfiles |
+| `update` | Only missing gemfiles | Yes, via update | Refresh lockfiles/dependencies using existing generated gemfiles |
+| `generate-install` | Yes | Yes, via install | First setup, or after intentional Appraisals changes |
+| `generate-update` | Yes | Yes, via update | Regenerate gemfiles, then update dependency locks |
+
+The deprecated rake task `rake appraisal:install` now delegates to
+`appraisal generate-install`, preserving its historical generate-and-install
+behavior while the CLI commands remain explicit.
+
 ### Command Options
 
-The `install` and `update` **built-in commands** support several options:
+Built-in dependency commands support the following options:
 
-**Important:** These options apply **only** to Appraisal's `install` and `update` commands.
-They do **not** apply when running external commands like `bundle install` or `bundle update`.
+**Important:** These options apply **only** to Appraisal's built-in dependency
+commands. They do **not** apply when running external commands like
+`bundle install` or `bundle update`.
 
 | Option | Description |
 |--------|-------------|
-| `--gem-manager`, `-g` | Gem manager to use: `bundler` (default) or `ore` |
-| `--jobs`, `-j` | Install gems in parallel using the given number of workers |
-| `--retry` | Retry network and git requests that have failed (default: 1) |
-| `--without` | A space-separated list of groups to skip during installation |
-| `--full-index` | Run bundle install with the full-index argument |
-| `--path` | Install gems in the specified directory |
+| `--gem-manager`, `-g` | Gem manager to use: `bundler` (default) or `ore`; applies to `install`, `update`, `generate-install`, and `generate-update` |
+| `--jobs`, `-j` | Install gems in parallel using the given number of workers; applies to `install` and `generate-install` |
+| `--retry` | Retry network and git requests that have failed; applies to `install` and `generate-install` (default: 1) |
+| `--without` | A space-separated list of groups to skip during installation; applies to `install` and `generate-install` |
+| `--full-index` | Run bundle install with the full-index argument; applies to `install` and `generate-install` |
+| `--path` | Install gems in the specified directory; applies to `install` and `generate-install` |
 
 ### Using Commands with Named Appraisals
 
 #### Using Appraisal's built-in commands with named appraisals
 
-When using Appraisal's `install` or `update` commands with a specific appraisal name,
-place the appraisal name first, then the command, then any options:
+When using Appraisal's built-in commands with a specific appraisal name, place
+the appraisal name first, then the command, then any options:
 
 ```bash
 # ✅ Correct order: appraisal <NAME> <COMMAND> [OPTIONS]
+bundle exec appraisal rails-7 generate
 bundle exec appraisal rails-7 install --gem-manager=ore
+bundle exec appraisal rails-7 generate-install --gem-manager=ore
 bundle exec appraisal rails-7 update rails --gem-manager=ore
+bundle exec appraisal rails-7 generate-update rails --gem-manager=ore
 bundle exec appraisal rails-7 install --jobs=4
 
 # ❌ Wrong order (won't work)
@@ -219,6 +341,9 @@ More examples with Appraisal's built-in commands:
 # Install dependencies for a specific appraisal
 bundle exec appraisal rails-7 install
 
+# Regenerate and install dependencies for a specific appraisal
+bundle exec appraisal rails-7 generate-install
+
 # Install with options
 bundle exec appraisal rails-7 install --gem-manager=ore --jobs=4
 
@@ -228,6 +353,10 @@ bundle exec appraisal rails-7 update
 # Update specific gems in a specific appraisal
 bundle exec appraisal rails-7 update rails rack
 bundle exec appraisal rails-7 update rails rack --gem-manager=ore
+
+# Regenerate before updating a specific appraisal
+bundle exec appraisal rails-7 generate-update
+bundle exec appraisal rails-7 generate-update rails rack
 ```
 
 #### Running external commands with named appraisals
@@ -612,6 +741,7 @@ Thanks for RTFM. ☺️
 [💎ruby-2.0i]: https://img.shields.io/badge/Ruby-2.0_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-2.1i]: https://img.shields.io/badge/Ruby-2.1_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-2.2i]: https://img.shields.io/badge/Ruby-2.2_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=white
+[💎ruby-2.3i]: https://img.shields.io/badge/Ruby-2.3_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-2.4i]: https://img.shields.io/badge/Ruby-2.4-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-2.5i]: https://img.shields.io/badge/Ruby-2.5-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-2.6i]: https://img.shields.io/badge/Ruby-2.6-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
@@ -661,7 +791,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.834-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.911-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/appraisal-rb/appraisal2/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
@@ -689,7 +819,7 @@ Thanks for RTFM. ☺️
 | Package | appraisal2 |
 | Description | 🔍️ Appraisal2 integrates with bundler and rake to test your library against different versions of dependencies in repeatable scenarios called "appraisals." |
 | Homepage | https://github.com/appraisal-rb/appraisal2 |
-| Source | https://github.com/appraisal-rb/appraisal2/tree/v3.0.8 |
+| Source | https://github.com/appraisal-rb/appraisal2/tree/v3.1.0 |
 | License | `MIT` |
 | Funding | https://github.com/sponsors/pboling, https://issuehunt.io/u/pboling, https://ko-fi.com/pboling, https://liberapay.com/pboling/donate, https://opencollective.com/appraisal-rb, https://patreon.com/galtzo, https://polar.sh/pboling, https://thanks.dev/u/gh/pboling, https://tidelift.com/funding/github/rubygems/appraisal2, https://www.buymeacoffee.com/pboling |
 <!-- kettle-jem:metadata:end -->

data/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version  | Supported |
 |----------|-----------|
-| 3.0.latest | ✅         |
+| 3.1.latest | ✅         |
 
 ## Security contact information
 

data/lib/appraisal/appraisal.rb

@@ -8,6 +8,7 @@ require "pathname"
 require "appraisal/gemfile"
 require "appraisal/command"
 require "appraisal/customize"
+require "appraisal/hooks"
 require "appraisal/utils"
 require "appraisal/gem_manager"
 
@@ -70,14 +71,14 @@ module Appraisal
     end
 
     def write_gemfile
+      content = ::Appraisal::Hooks.run_transform_gemfile(self, gemfile_path, generated_gemfile)
       File.open(gemfile_path, "w") do |file|
-        signature =
-          Customize.heading(self) || "This file was generated by Appraisal2"
-        file.puts([comment_lines(signature), quoted_gemfile].join("\n\n"))
+        file.write(content)
       end
     end
 
     def install(options = {})
+      write_gemfile unless File.exist?(gemfile_path)
       gem_manager = options.delete(:gem_manager) || options.delete("gem_manager") ||
         options.delete(:"gem-manager") || options.delete("gem-manager")
       manager = GemManager::Factory.create(gemfile_path, project_root, :manager => gem_manager)
@@ -85,6 +86,7 @@ module Appraisal
     end
 
     def update(gems = [], options = {})
+      write_gemfile unless File.exist?(gemfile_path)
       gem_manager = options[:gem_manager] || options["gem_manager"] ||
         options[:"gem-manager"] || options["gem-manager"]
       manager = GemManager::Factory.create(gemfile_path, project_root, :manager => gem_manager)
@@ -136,6 +138,12 @@ module Appraisal
       name.gsub(/[^\w.]/, "_")
     end
 
+    def generated_gemfile
+      signature =
+        Customize.heading(self) || "This file was generated by Appraisal2"
+      [comment_lines(signature), quoted_gemfile].join("\n\n") + "\n"
+    end
+
     def comment_lines(heading)
       heading.lines.map do |line|
         if line.lstrip.empty?

data/lib/appraisal/appraisal_file.rb

@@ -41,6 +41,16 @@ module Appraisal
       Customize.new(args)
     end
 
+    def plugin(name, *args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      require_path = options.key?(:require) ? options[:require] : name
+      optional = options.key?(:optional) ? options[:optional] : false
+
+      require require_path if require_path
+    rescue LoadError
+      raise unless optional
+    end
+
     private
 
     def run(definitions)

data/lib/appraisal/bundler_dsl.rb

@@ -44,6 +44,10 @@ module Appraisal
       @eval_gemfile << [path, contents]
     end
 
+    def generator_only(&_block)
+      nil
+    end
+
     def gem(name, *requirements)
       @dependencies.add(name, substitute_git_source(requirements))
     end

data/lib/appraisal/cli.rb

@@ -53,7 +53,7 @@ module Appraisal
       end
     end
 
-    desc "install", "Resolve and install dependencies for each appraisal"
+    desc "install", "Resolve and install dependencies for each generated appraisal gemfile"
     method_option "jobs",
       :aliases => "j",
       :type => :numeric,
@@ -78,8 +78,6 @@ module Appraisal
         "Bundler will remember this option."
 
     def install
-      invoke(:generate, [], {})
-
       install_options = options.to_h
       AppraisalFile.each do |appraisal|
         appraisal.install(install_options)
@@ -87,6 +85,34 @@ module Appraisal
       end
     end
 
+    desc "generate-install", "Generate gemfiles, then resolve and install dependencies for each appraisal"
+    method_option "jobs",
+      :aliases => "j",
+      :type => :numeric,
+      :default => 1,
+      :banner => "SIZE",
+      :desc => "Install gems in parallel using the given number of workers."
+    method_option "retry",
+      :type => :numeric,
+      :default => 1,
+      :desc => "Retry network and git requests that have failed"
+    method_option "without",
+      :banner => "GROUP_NAMES",
+      :desc => "A space-separated list of groups referencing gems to skip " \
+        "during installation. Bundler will remember this option."
+    method_option "full-index",
+      :type => :boolean,
+      :desc => "Run bundle install with the " \
+        "full-index argument."
+    method_option "path",
+      :type => :string,
+      :desc => "Install gems in the specified directory. " \
+        "Bundler will remember this option."
+    def generate_install
+      invoke(:generate, [], {})
+      invoke(:install, [], options.to_h)
+    end
+
     desc "generate", "Generate a gemfile for each appraisal"
     def generate
       AppraisalFile.each do |appraisal|
@@ -99,10 +125,8 @@ module Appraisal
       FileUtils.rm_f(Dir["gemfiles/*.{gemfile,gemfile.lock}"])
     end
 
-    desc "update [LIST_OF_GEMS]", "Remove all generated gemfiles and lockfiles, resolve, and install dependencies again"
+    desc "update [LIST_OF_GEMS]", "Update dependencies for each generated appraisal gemfile"
     def update(*gems)
-      invoke(:generate, [], {})
-
       gem_manager = options["gem-manager"] || options[:gem_manager]
       update_options = gem_manager ? {:gem_manager => gem_manager} : {}
       AppraisalFile.each do |appraisal|
@@ -110,6 +134,12 @@ module Appraisal
       end
     end
 
+    desc "generate-update [LIST_OF_GEMS]", "Generate gemfiles, then update dependencies for each appraisal"
+    def generate_update(*gems)
+      invoke(:generate, [], {})
+      update(*gems)
+    end
+
     desc "list", "List the names of the defined appraisals"
     def list
       AppraisalFile.new.appraisals.each { |appraisal| puts appraisal.name }
@@ -132,8 +162,10 @@ module Appraisal
         # This handles cases where Thor doesn't pass arguments
         actual_args = (args.empty? && ARGV.any?) ? ARGV.dup : args
 
-        # Check if the first argument is a Thor command (install or update)
-        if actual_args.first == "install"
+        # Check if the first argument is an appraisal subcommand.
+        if actual_args.first == "generate"
+          matching_appraisal.write_gemfile
+        elsif actual_args.first == "install"
           # Extract Thor options from the remaining arguments
           # Filter out the command name and pass options to install
           filtered_args = actual_args[1..-1] || []
@@ -145,6 +177,15 @@ module Appraisal
           gem_manager = options["gem-manager"] || options[:gem_manager]
           parsed_options[:gem_manager] = gem_manager if gem_manager && !parsed_options.key?(:gem_manager)
 
+          matching_appraisal.install(parsed_options)
+          matching_appraisal.relativize
+        elsif actual_args.first == "generate-install"
+          filtered_args = actual_args[1..-1] || []
+          parsed_options = parse_external_options(filtered_args)
+
+          gem_manager = options["gem-manager"] || options[:gem_manager]
+          parsed_options[:gem_manager] = gem_manager if gem_manager && !parsed_options.key?(:gem_manager)
+
           matching_appraisal.write_gemfile
           matching_appraisal.install(parsed_options)
           matching_appraisal.relativize
@@ -157,6 +198,15 @@ module Appraisal
           gem_manager = options["gem-manager"] || options[:gem_manager]
           parsed_options[:gem_manager] = gem_manager if gem_manager && !parsed_options.key?(:gem_manager)
 
+          matching_appraisal.update(gems, parsed_options)
+        elsif actual_args.first == "generate-update"
+          filtered_args = actual_args[1..-1] || []
+          gems, parsed_options = extract_gems_and_options(filtered_args)
+
+          gem_manager = options["gem-manager"] || options[:gem_manager]
+          parsed_options[:gem_manager] = gem_manager if gem_manager && !parsed_options.key?(:gem_manager)
+
+          matching_appraisal.write_gemfile
           matching_appraisal.update(gems, parsed_options)
         else
           # Run as an external command

data/lib/appraisal/hooks.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Appraisal
+  # Lifecycle hooks used by companion gems to extend Appraisal without
+  # monkey-patching command or generation internals.
+  module Hooks
+    GEMFILE_TRANSFORM_MUTEX = Mutex.new
+    GEMFILE_TRANSFORMS = [].freeze
+
+    class GemfileContext
+      attr_accessor :content
+      attr_reader :appraisal, :path
+
+      def initialize(appraisal, path, content)
+        @appraisal = appraisal
+        @path = path
+        @content = content
+      end
+    end
+
+    class << self
+      def transform_gemfile(&block)
+        raise ArgumentError, "transform_gemfile requires a block" unless block
+
+        GEMFILE_TRANSFORM_MUTEX.synchronize do
+          set_gemfile_transforms(gemfile_transforms + [block])
+        end
+      end
+
+      def run_transform_gemfile(appraisal, path, content)
+        context = GemfileContext.new(appraisal, path, content)
+        gemfile_transforms.each do |hook|
+          result = if hook.arity == 1
+            hook.call(context.content)
+          else
+            hook.call(context.content, context)
+          end
+          context.content = result unless result.nil?
+        end
+        context.content
+      end
+
+      def reset!
+        GEMFILE_TRANSFORM_MUTEX.synchronize do
+          set_gemfile_transforms([])
+        end
+      end
+
+      private
+
+      def gemfile_transforms
+        ::Appraisal::Hooks.const_get(:GEMFILE_TRANSFORMS)
+      end
+
+      def set_gemfile_transforms(transforms)
+        ::Appraisal::Hooks.__send__(:remove_const, :GEMFILE_TRANSFORMS)
+        ::Appraisal::Hooks.const_set(:GEMFILE_TRANSFORMS, transforms.freeze)
+      end
+    end
+  end
+
+  class << self
+    def transform_gemfile(&block)
+      Hooks.transform_gemfile(&block)
+    end
+  end
+end

data/lib/appraisal/task.rb

@@ -19,8 +19,8 @@ module Appraisal
         desc("DEPRECATED: Resolve and install dependencies for each appraisal")
         task(:install) do
           warn("`rake appraisal:install` task is deprecated and will be removed soon. " \
-            "Please use `appraisal install`.")
-          exec("bundle exec appraisal install")
+            "Please use `appraisal generate-install`.")
+          exec("bundle exec appraisal generate-install")
         end
 
         desc("DEPRECATED: Remove all generated gemfiles from gemfiles/ folder")

data/lib/appraisal/version.rb

@@ -2,7 +2,7 @@
 
 module Appraisal
   module Version
-    VERSION = "3.0.9"
+    VERSION = "3.1.1"
   end
   VERSION = Version::VERSION # Traditional constant location
 end

data/lib/appraisal2/version.rb

@@ -2,7 +2,7 @@
 
 module Appraisal2
   module Version
-    VERSION = "3.0.9"
+    VERSION = "3.1.1"
   end
   VERSION = Version::VERSION # Traditional Constant Location
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appraisal2
 version: !ruby/object:Gem::Version
-  version: 3.0.9
+  version: 3.1.1
 platform: ruby
 authors:
 - Peter Boling
@@ -421,6 +421,7 @@ files:
 - lib/appraisal/gemspec.rb
 - lib/appraisal/git.rb
 - lib/appraisal/group.rb
+- lib/appraisal/hooks.rb
 - lib/appraisal/ordered_hash.rb
 - lib/appraisal/path.rb
 - lib/appraisal/platform.rb
@@ -436,10 +437,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://appraisal2.galtzo.com
-  source_code_uri: https://github.com/appraisal-rb/appraisal2/tree/v3.0.9
-  changelog_uri: https://github.com/appraisal-rb/appraisal2/blob/v3.0.9/CHANGELOG.md
+  source_code_uri: https://github.com/appraisal-rb/appraisal2/tree/v3.1.1
+  changelog_uri: https://github.com/appraisal-rb/appraisal2/blob/v3.1.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/appraisal-rb/appraisal2/issues
-  documentation_uri: https://www.rubydoc.info/gems/appraisal2/3.0.9
+  documentation_uri: https://www.rubydoc.info/gems/appraisal2/3.1.1
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/appraisal-rb/appraisal2/wiki
   news_uri: https://www.railsbling.com/tags/appraisal2