[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.

ruby/rubygems@9e081b0689

Author: schneems

lib/bundler/cli.rb

@@ -299,6 +299,7 @@ def show(gem_name = nil)
     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"

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 @@ def run
         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 @@ def run
       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)

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)
 

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)

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 @@
     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 @@
         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 @@
         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 @@
         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 @@
         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 @@
       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 @@
       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 @@
       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 @@
       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