Improve internal API to make bundleup easier to use in Ruby scripts

README.md

@@ -75,6 +75,38 @@ Note that `--update-gemfile` will _not_ modify Gemfile entries that contain a co
 gem 'sidekiq', '~> 5.2' # our monkey patch doesn't work on 6.0+
 ```
 
+### Integrate bundlup in a script
+
+`Bundleup::CLI` gives you two methods to track updated and pinned gems:
+
+```ruby
+cli = Bundleup::CLI.new([])
+cli.run
+cli.updated_gems
+# > ["rubocop"]
+
+cli.pinned_gems
+# > ["rake"]
+```
+
+You can then easily create scripts to perform any actions such as running tests, running rubocop, or commit changes.
+
+```ruby
+cli = Bundleup::CLI.new([])
+cli.run
+
+if cli.updated_gems.any?
+  system "bundle exec rspec"
+elsif cli.updated_gems.include?("rubocop")
+  system "bundle exec rubocop"
+end
+
+if cli.updated_gems.any?
+  system "git commit -m \"Update gems dependencies\" -- Gemfile.lock"
+end
+```
+
+
 ## How bundleup works
 
 bundleup starts by making a backup copy of your Gemfile.lock. Next it runs `bundle check` (and `bundle install` if any gems are missing in your local environment), `bundle list`, then `bundle update` and `bundle list` again to find what gems versions are being used before and after Bundler does its updating magic. (Since gems are actually being installed into your Ruby environment during these steps, the process may take a few moments to complete, especially if gems with native extensions need to be compiled.)

lib/bundleup/cli.rb

@@ -8,14 +8,21 @@ class CLI
     extend Forwardable
     def_delegators :Bundleup, :commands, :logger
 
+    attr_reader :updated_gems, :pinned_gems
+
     def initialize(args)
       @args = args.dup
       @update_gemfile = @args.delete("--update-gemfile")
+      @updated_gems = []
+      @pinned_gems = []
     end
 
     def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       print_usage && return if (args & %w[-h --help]).any?
 
+      @updated_gems = []
+      @pinned_gems = []
+
       assert_gemfile_and_lock_exist!
 
       logger.puts "Please wait a moment while I upgrade your Gemfile.lock..."
@@ -32,6 +39,9 @@ def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           logger.puts pin_report unless pin_report.empty?
 
           if logger.confirm?("Do you want to apply these changes?")
+            @updated_gems = update_report.updated_gems
+            @pinned_gems = pin_report.pinned_gems
+
             logger.ok "Done!"
           else
             backup.restore

lib/bundleup/pin_report.rb

@@ -24,6 +24,10 @@ def rows
       end
     end
 
+    def pinned_gems
+      outdated_gems.keys.sort
+    end
+
     private
 
     attr_reader :gem_versions, :outdated_gems, :gem_comments

lib/bundleup/update_report.rb

@@ -25,6 +25,12 @@ def rows
       end
     end
 
+    def updated_gems
+      gem_names.reject do |gem|
+        old_versions[gem] == new_versions[gem]
+      end
+    end
+
     private
 
     attr_reader :old_versions, :new_versions

test/bundleup/cli_test.rb

@@ -76,6 +76,42 @@ def test_update_gemfile_flag # rubocop:disable Minitest/MultipleAssertions
     refute_match(/^gem "rubocop", "0.89.0"$/, updated_gemfile)
   end
 
+  def test_returned_updated_and_pinned_gems_after_run
+    cli = Bundleup::CLI.new([])
+
+    within_copy_of_sample_project do
+      capturing_plain_output(stdin: "y\n") do
+        with_clean_bundler_env do
+          cli.run
+        end
+      end
+    end
+
+    assert_kind_of(Array, cli.updated_gems)
+    assert_kind_of(Array, cli.pinned_gems)
+    assert_includes(cli.updated_gems, "mail")
+    assert_includes(cli.updated_gems, "mocha")
+    assert_includes(cli.pinned_gems, "rake")
+    assert_includes(cli.pinned_gems, "rubocop")
+  end
+
+  def test_returned_no_chenged_gems_after_rejected_changes
+    cli = Bundleup::CLI.new([])
+
+    within_copy_of_sample_project do
+      capturing_plain_output(stdin: "n\n") do
+        with_clean_bundler_env do
+          cli.run
+        end
+      end
+    end
+
+    assert_kind_of(Array, cli.updated_gems)
+    assert_kind_of(Array, cli.pinned_gems)
+    assert_empty(cli.updated_gems)
+    assert_empty(cli.pinned_gems)
+  end
+
   private
 
   def with_clean_bundler_env(&block)

test/bundleup/pin_report_test.rb

@@ -43,4 +43,17 @@ def test_generates_sorted_table_with_pins_and_gray_color_comments
       REPORT
     end
   end
+
+  def test_list_pinned_gems
+    report = Bundleup::PinReport.new(
+      gem_versions: { "rake" => "12.3.3", "rubocop" => "0.89.0" },
+      outdated_gems: {
+        "rake" => { newest: "13.0.1", pin: "~> 12.0" },
+        "rubocop" => { newest: "0.89.1", pin: "= 0.89.0" }
+      },
+      gem_comments: {}
+    )
+
+    assert_equal(%w[rake rubocop], report.pinned_gems)
+  end
 end

test/bundleup/update_report_test.rb

@@ -94,4 +94,21 @@ def test_colorizes_rows_according_to_semver
       REPORT
     end
   end
+
+  def test_list_updated_gems
+    report = Bundleup::UpdateReport.new(
+      old_versions: {
+        "i18n" => "1.8.2",
+        "zeitwerk" => "2.4.0",
+        "json" => "2.2.0"
+      },
+      new_versions: {
+        "i18n" => "1.8.5",
+        "zeitwerk" => "2.4.0",
+        "parser" => "2.7.1.4"
+      }
+    )
+
+    assert_equal(%w[i18n json parser], report.updated_gems)
+  end
 end