[rubygems/rubygems] Introduce `bundle list --format=json`

The `bundle list` command is a convenient way for human to know what gems and versions are available. By introducing a `--format=json` option, we can provide the same information to machines in a stable format that is robust to UI additions or modifications. It indirectly supports  `Gemfile.lock` modifications by discouraging external tools from attempting to parse that format.

This addition allows for the scripting of installation tools, such as buildpacks, that wish to branch logic based on gem versions. For example:

```ruby
require "json"

command = "bundle list --format=json"
output = `#{command}`
raise "Command `#{command}` errored: #{output}" unless $?.success?

railties = JSON.parse(output).find {|gem| gem["name"] == railties }
if railties && Gem::Version.new(railties["version"]) >= Gem::Version.new("7")
  puts "Using Rails greater than 7!"
end
```

The top level is an object with a single key, "gems", this structure allows us to add other information in the future (should we desire) without having to change the json schema.

https://github.com/rubygems/rubygems/commit/9e081b0689

5 files changed, 152 insertions, 2 deletions

diff --git a/lib/bundler/cli.rb b/lib/bundler/cli.rb
index 8c4e3c36a7..65bf8eee83 100644
--- a/lib/bundler/cli.rb
+++ b/lib/bundler/cli.rb
@@ -299,6 +299,7 @@ module Bundler
     method_option "name-only", type: :boolean, banner: "print only the gem names"
     method_option "only-group", type: :array, default: [], banner: "print gems from a given set of groups"
     method_option "without-group", type: :array, default: [], banner: "print all gems except from a given set of groups"
+    method_option "format", type: :string, banner: "format output ('json' is the only supported format)"
     method_option "paths", type: :boolean, banner: "print the path to each gem in the bundle"
     def list
       require_relative "cli/list"
diff --git a/lib/bundler/cli/list.rb b/lib/bundler/cli/list.rb
index f56bf5b86a..6a467f45a9 100644
--- a/lib/bundler/cli/list.rb
+++ b/lib/bundler/cli/list.rb
@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Bundler
   class CLI::List
     def initialize(options)
       @options = options
       @without_group = options["without-group"].map(&:to_sym)
       @only_group = options["only-group"].map(&:to_sym)
+      @format = options["format"]
     end
 
     def run
@@ -25,6 +28,36 @@ module Bundler
         end
       end.reject {|s| s.name == "bundler" }.sort_by(&:name)
 
+      case @format
+      when "json"
+        print_json(specs: specs)
+      when nil
+        print_human(specs: specs)
+      else
+        raise InvalidOption, "Unknown option`--format=#{@format}`. Supported formats: `json`"
+      end
+    end
+
+    private
+
+    def print_json(specs:)
+      gems = if @options["name-only"]
+        specs.map {|s| { name: s.name } }
+      else
+        specs.map do |s|
+          {
+            name: s.name,
+            version: s.version.to_s,
+            git_version: s.git_version&.strip,
+          }.tap do |h|
+            h[:path] = s.full_gem_path if @options["paths"]
+          end
+        end
+      end
+      Bundler.ui.info({ gems: gems }.to_json)
+    end
+
+    def print_human(specs:)
       return Bundler.ui.info "No gems in the Gemfile" if specs.empty?
 
       return specs.each {|s| Bundler.ui.info s.name } if @options["name-only"]
@@ -37,8 +70,6 @@ module Bundler
       Bundler.ui.info "Use `bundle info` to print more detailed information about a gem"
     end
 
-    private
-
     def verify_group_exists(groups)
       (@without_group + @only_group).each do |group|
         raise InvalidOption, "`#{group}` group could not be found." unless groups.include?(group)
diff --git a/lib/bundler/man/bundle-list.1 b/lib/bundler/man/bundle-list.1
index 26c2833218..7698fe16cc 100644
--- a/lib/bundler/man/bundle-list.1
+++ b/lib/bundler/man/bundle-list.1
@@ -19,6 +19,8 @@ bundle list \-\-without\-group test
 bundle list \-\-only\-group dev
 .P
 bundle list \-\-only\-group dev test \-\-paths
+.P
+bundle list \-\-format json
 .SH "OPTIONS"
 .TP
 \fB\-\-name\-only\fR
@@ -32,4 +34,7 @@ A space\-separated list of groups of gems to skip during printing\.
 .TP
 \fB\-\-only\-group=<list>\fR
 A space\-separated list of groups of gems to print\.
+.TP
+\fB\-\-format=FORMAT\fR
+Format output ('json' is the only supported format)
 
diff --git a/lib/bundler/man/bundle-list.1.ronn b/lib/bundler/man/bundle-list.1.ronn
index 81bee0ac33..9ec2b13282 100644
--- a/lib/bundler/man/bundle-list.1.ronn
+++ b/lib/bundler/man/bundle-list.1.ronn
@@ -21,6 +21,8 @@ bundle list --only-group dev
 
 bundle list --only-group dev test --paths
 
+bundle list --format json
+
 ## OPTIONS
 
 * `--name-only`:
@@ -34,3 +36,6 @@ bundle list --only-group dev test --paths
 
 * `--only-group=<list>`:
   A space-separated list of groups of gems to print.
+
+* `--format=FORMAT`:
+  Format output ('json' is the only supported format)
diff --git a/spec/bundler/commands/list_spec.rb b/spec/bundler/commands/list_spec.rb
index e8ed863310..c890646a81 100644
--- a/spec/bundler/commands/list_spec.rb
+++ b/spec/bundler/commands/list_spec.rb
@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
+require "json"
+
 RSpec.describe "bundle list" do
+  def find_gem_name(json:, name:)
+    parse_json(json)["gems"].detect {|h| h["name"] == name }
+  end
+
+  def parse_json(json)
+    JSON.parse(json)
+  end
+
   context "in verbose mode" do
     it "logs the actual flags passed to the command" do
       install_gemfile <<-G
@@ -29,6 +39,20 @@ RSpec.describe "bundle list" do
     end
   end
 
+  context "with invalid format option" do
+    before do
+      install_gemfile <<-G
+        source "https://gem.repo1"
+      G
+    end
+
+    it "raises an error" do
+      bundle "list --format=nope", raise_on_error: false
+
+      expect(err).to eq "Unknown option`--format=nope`. Supported formats: `json`"
+    end
+  end
+
   describe "with without-group option" do
     before do
       install_gemfile <<-G
@@ -48,6 +72,17 @@ RSpec.describe "bundle list" do
         expect(out).to include("  * rails (2.3.2)")
         expect(out).not_to include("  * rspec (1.2.7)")
       end
+
+      it "prints the gems not in the specified group with json" do
+        bundle "list --without-group test --format=json"
+
+        gem = find_gem_name(json: out, name: "myrack")
+        expect(gem["version"]).to eq("1.0.0")
+        gem = find_gem_name(json: out, name: "rails")
+        expect(gem["version"]).to eq("2.3.2")
+        gem = find_gem_name(json: out, name: "rspec")
+        expect(gem).to be_nil
+      end
     end
 
     context "when group is not found" do
@@ -66,6 +101,17 @@ RSpec.describe "bundle list" do
         expect(out).not_to include("  * rails (2.3.2)")
         expect(out).not_to include("  * rspec (1.2.7)")
       end
+
+      it "prints the gems not in the specified groups with json" do
+        bundle "list --without-group test production --format=json"
+
+        gem = find_gem_name(json: out, name: "myrack")
+        expect(gem["version"]).to eq("1.0.0")
+        gem = find_gem_name(json: out, name: "rails")
+        expect(gem).to be_nil
+        gem = find_gem_name(json: out, name: "rspec")
+        expect(gem).to be_nil
+      end
     end
   end
 
@@ -87,6 +133,15 @@ RSpec.describe "bundle list" do
         expect(out).to include("  * myrack (1.0.0)")
         expect(out).not_to include("  * rspec (1.2.7)")
       end
+
+      it "prints the gems in the specified group with json" do
+        bundle "list --only-group default --format=json"
+
+        gem = find_gem_name(json: out, name: "myrack")
+        expect(gem["version"]).to eq("1.0.0")
+        gem = find_gem_name(json: out, name: "rspec")
+        expect(gem).to be_nil
+      end
     end
 
     context "when group is not found" do
@@ -105,6 +160,17 @@ RSpec.describe "bundle list" do
         expect(out).to include("  * rails (2.3.2)")
         expect(out).not_to include("  * rspec (1.2.7)")
       end
+
+      it "prints the gems in the specified groups with json" do
+        bundle "list --only-group default production --format=json"
+
+        gem = find_gem_name(json: out, name: "myrack")
+        expect(gem["version"]).to eq("1.0.0")
+        gem = find_gem_name(json: out, name: "rails")
+        expect(gem["version"]).to eq("2.3.2")
+        gem = find_gem_name(json: out, name: "rspec")
+        expect(gem).to be_nil
+      end
     end
   end
 
@@ -124,6 +190,15 @@ RSpec.describe "bundle list" do
       expect(out).to include("myrack")
       expect(out).to include("rspec")
     end
+
+    it "prints only the name of the gems in the bundle with json" do
+      bundle "list --name-only --format=json"
+
+      gem = find_gem_name(json: out, name: "myrack")
+      expect(gem.keys).to eq(["name"])
+      gem = find_gem_name(json: out, name: "rspec")
+      expect(gem.keys).to eq(["name"])
+    end
   end
 
   context "with paths option" do
@@ -158,6 +233,27 @@ RSpec.describe "bundle list" do
       expect(out).to match(%r{.*\/git_test\-\w})
       expect(out).to match(%r{.*\/gemspec_test})
     end
+
+    it "prints the path of each gem in the bundle with json" do
+      bundle "list --paths --format=json"
+
+      gem = find_gem_name(json: out, name: "rails")
+      expect(gem["path"]).to match(%r{.*\/rails\-2\.3\.2})
+      expect(gem["git_version"]).to be_nil
+
+      gem = find_gem_name(json: out, name: "myrack")
+      expect(gem["path"]).to match(%r{.*\/myrack\-1\.2})
+      expect(gem["git_version"]).to be_nil
+
+      gem = find_gem_name(json: out, name: "git_test")
+      expect(gem["path"]).to match(%r{.*\/git_test\-\w})
+      expect(gem["git_version"]).to be_truthy
+      expect(gem["git_version"].strip).to eq(gem["git_version"])
+
+      gem = find_gem_name(json: out, name: "gemspec_test")
+      expect(gem["path"]).to match(%r{.*\/gemspec_test})
+      expect(gem["git_version"]).to be_nil
+    end
   end
 
   context "when no gems are in the gemfile" do
@@ -171,6 +267,11 @@ RSpec.describe "bundle list" do
       bundle "list"
       expect(out).to include("No gems in the Gemfile")
     end
+
+    it "prints empty json" do
+      bundle "list --format=json"
+      expect(parse_json(out)["gems"]).to eq([])
+    end
   end
 
   context "without options" do
@@ -187,6 +288,13 @@ RSpec.describe "bundle list" do
       bundle "list"
       expect(out).to include("  * myrack (1.0.0)")
     end
+
+    it "lists gems installed in the bundle with json" do
+      bundle "list --format=json"
+
+      gem = find_gem_name(json: out, name: "myrack")
+      expect(gem["version"]).to eq("1.0.0")
+    end
   end
 
   context "when using the ls alias" do