simplecov 0.22.0 → 1.3.0

data/lib/simplecov/cli/annotations.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module SimpleCov
+  module CLI
+    # The `--annotate KIND` output shared by `uncovered` and `patch`: each command
+    # reduces its answer to diagnostics (a path, a contiguous missed line range,
+    # and the criterion that missed), and one emitter per CI host renders them in
+    # that host's native inline-annotation channel, so a gap surfaces on the diff
+    # with no upload step and no extra gem.
+    module Annotations
+      KINDS = %w[github gitlab rdjson azure teamcity buildkite].freeze
+
+      MESSAGES = {
+        line: "Not covered by tests",
+        branch: "Branch not covered by tests",
+        method: "Method not covered by tests"
+      }.freeze
+
+      DESCRIPTIONS = {
+        line: "Lines the tests never executed",
+        branch: "Branches the tests never took",
+        method: "Methods the tests never called"
+      }.freeze
+
+      SOURCE = {"name" => "simplecov", "url" => "https://github.com/simplecov-ruby/simplecov"}.freeze
+
+      # TeamCity's service message grammar and Azure's logging command grammar
+      # each reserve a few characters in attribute values.
+      TEAMCITY_ESCAPES = {"|" => "||", "'" => "|'", "[" => "|[", "]" => "|]", "\n" => "|n", "\r" => "|r"}.freeze
+      AZURE_ESCAPES = {"%" => "%AZP25", ";" => "%3B", "]" => "%5D", "\n" => "%0A", "\r" => "%0D"}.freeze
+
+      extend self
+
+      def issue(opts)
+        kind = opts.fetch(:annotate)
+        return nil unless kind
+        return "unknown --annotate #{kind.inspect} (expected #{expected_kinds})" unless KINDS.include?(kind)
+
+        "cannot combine --annotate with --json" if opts.fetch(:json)
+      end
+
+      def expected_kinds
+        *rest, last = KINDS
+        "#{rest.join(", ")}, or #{last}"
+      end
+
+      def diagnostics(path, missed, criterion)
+        missed.slice_when { |previous, current| current > previous + 1 }.map do |run|
+          {path: path, first: run.first, last: run.last, criterion: criterion, message: MESSAGES.fetch(criterion)}
+        end
+      end
+
+      def emit(stdout, kind, diagnostics)
+        case kind
+        when "github" then github(stdout, diagnostics)
+        when "gitlab" then stdout.puts(JSON.pretty_generate(gitlab(diagnostics)))
+        when "rdjson" then stdout.puts(JSON.pretty_generate(rdjson(diagnostics)))
+        when "azure" then azure(stdout, diagnostics)
+        when "teamcity" then teamcity(stdout, diagnostics)
+        else buildkite(stdout, diagnostics)
+        end
+      end
+
+      def github(stdout, diagnostics)
+        diagnostics.each do |diagnostic|
+          stdout.puts("::warning file=#{diagnostic.fetch(:path)},line=#{diagnostic.fetch(:first)}," \
+                      "endLine=#{diagnostic.fetch(:last)}::#{diagnostic.fetch(:message)}")
+        end
+      end
+
+      # GitLab's Code Quality report, a subset of the Code Climate spec, read from
+      # a `codequality` artifact for merge request annotations.
+      def gitlab(diagnostics)
+        diagnostics.map do |diagnostic|
+          {
+            "description" => diagnostic.fetch(:message),
+            "check_name" => "coverage",
+            "fingerprint" => fingerprint(diagnostic),
+            "severity" => "minor",
+            "location" => {
+              "path" => diagnostic.fetch(:path),
+              "lines" => {"begin" => diagnostic.fetch(:first), "end" => diagnostic.fetch(:last)}
+            }
+          }
+        end
+      end
+
+      def fingerprint(diagnostic)
+        Digest::SHA256.hexdigest("#{diagnostic.fetch(:path)}:#{diagnostic.fetch(:first)}-#{diagnostic.fetch(:last)}:" \
+                                 "#{diagnostic.fetch(:criterion)}")
+      end
+
+      # reviewdog's Diagnostic Format, which reviewdog posts to whichever host it
+      # runs under.
+      def rdjson(diagnostics)
+        {"source" => SOURCE, "severity" => "WARNING", "diagnostics" => diagnostics.map { |d| rdjson_diagnostic(d) }}
+      end
+
+      def rdjson_diagnostic(diagnostic)
+        {
+          "message" => diagnostic.fetch(:message),
+          "location" => {
+            "path" => diagnostic.fetch(:path),
+            "range" => {"start" => {"line" => diagnostic.fetch(:first)}, "end" => {"line" => diagnostic.fetch(:last)}}
+          },
+          "severity" => "WARNING",
+          "code" => {"value" => diagnostic.fetch(:criterion).to_s}
+        }
+      end
+
+      # Azure Pipelines logging commands carry one line number, so a range is
+      # spelled out in the message.
+      def azure(stdout, diagnostics)
+        diagnostics.each do |diagnostic|
+          stdout.puts("##vso[task.logissue type=warning;sourcepath=#{escape(diagnostic.fetch(:path), AZURE_ESCAPES)};" \
+                      "linenumber=#{diagnostic.fetch(:first)}]#{described(diagnostic)}")
+        end
+      end
+
+      # TeamCity's code inspection service messages: each criterion is one
+      # inspection type, declared once before its first inspection.
+      def teamcity(stdout, diagnostics)
+        diagnostics.group_by { |diagnostic| diagnostic.fetch(:criterion) }.each do |criterion, group|
+          id = "simplecov.#{criterion}"
+          stdout.puts(service_message("inspectionType", id: id, name: MESSAGES.fetch(criterion),
+            description: DESCRIPTIONS.fetch(criterion), category: "Code coverage"))
+          group.each do |diagnostic|
+            stdout.puts(service_message("inspection", typeId: id, message: described(diagnostic),
+              file: diagnostic.fetch(:path), line: diagnostic.fetch(:first), SEVERITY: "WARNING"))
+          end
+        end
+      end
+
+      def service_message(name, attributes)
+        body = attributes.map { |key, value| "#{key}='#{escape(value.to_s, TEAMCITY_ESCAPES)}'" }.join(" ")
+        "##teamcity[#{name} #{body}]"
+      end
+
+      # Buildkite has no per-line channel; its annotations are Markdown, so this
+      # is the body for `buildkite-agent annotate`.
+      def buildkite(stdout, diagnostics)
+        sections = diagnostics.group_by { |diagnostic| diagnostic.fetch(:message) }.map do |message, group|
+          (["#### #{message}"] + group.map { |diagnostic| "- `#{diagnostic.fetch(:path)}:#{range(diagnostic)}`" }).join("\n")
+        end
+        stdout.puts(sections.join("\n\n")) unless sections.empty?
+      end
+
+      def described(diagnostic)
+        return diagnostic.fetch(:message) if diagnostic.fetch(:first).equal?(diagnostic.fetch(:last))
+
+        "#{diagnostic.fetch(:message)} (lines #{range(diagnostic)})"
+      end
+
+      def range(diagnostic)
+        [diagnostic.fetch(:first), diagnostic.fetch(:last)].uniq.join("-")
+      end
+
+      def escape(text, escapes)
+        text.gsub(Regexp.union(escapes.keys), escapes)
+      end
+    end
+  end
+end

data/lib/simplecov/cli/badge/svg.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Badge
+      # Renders the badge SVG in shields.io's flat style: 20px tall with 3px
+      # rounded corners, the label on #555 and the value on its ladder color, each
+      # text drawn twice for the drop shadow at 10x scale. `textLength` pins the
+      # layout, so the estimated segment widths never let glyphs spill.
+      module Svg
+        extend self
+
+        COLORS = [[90, "#4c1"], [80, "#97ca00"], [70, "#a4a61d"], [60, "#dfb317"], [50, "#fe7d37"]].freeze
+
+        def color(percent)
+          rung = COLORS.detect { |floor, _color| percent >= floor }
+          rung ? rung.fetch(1) : "#e05d44"
+        end
+
+        def render(label:, percent:)
+          value = format("%.2f%%", percent)
+          document(label: escape(label), value: value, fill: color(percent),
+            geo: geometry(width(label), width(value)))
+        end
+
+        # Estimates 11px Verdana; `textLength` absorbs the error.
+        def width(text)
+          (7 * text.length) + 10
+        end
+
+        # The scale(.1) trick draws text at 10x and shrinks it, so the text
+        # coordinates live in a 10x space: centers at 10 * (offset + width / 2) and
+        # textLength spanning the width less padding.
+        def geometry(label_width, value_width)
+          {label_width: label_width, value_width: value_width, total: label_width + value_width,
+           label_x: 5 * label_width, value_x: (10 * label_width) + (5 * value_width),
+           label_span: 10 * (label_width - 10), value_span: 10 * (value_width - 10)}
+        end
+
+        def escape(text)
+          text.gsub(/[&<>"]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;")
+        end
+
+        def document(label:, value:, fill:, geo:)
+          <<~SVG
+            <svg xmlns="http://www.w3.org/2000/svg" width="#{geo.fetch(:total)}" height="20" role="img" aria-label="#{label}: #{value}">
+              <title>#{label}: #{value}</title>
+              <linearGradient id="s" x2="0" y2="100%">
+                <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+                <stop offset="1" stop-opacity=".1"/>
+              </linearGradient>
+              <clipPath id="r"><rect width="#{geo.fetch(:total)}" height="20" rx="3" fill="#fff"/></clipPath>
+              <g clip-path="url(#r)">
+                <rect width="#{geo.fetch(:label_width)}" height="20" fill="#555"/>
+                <rect x="#{geo.fetch(:label_width)}" width="#{geo.fetch(:value_width)}" height="20" fill="#{fill}"/>
+                <rect width="#{geo.fetch(:total)}" height="20" fill="url(#s)"/>
+              </g>
+              <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+                <text aria-hidden="true" x="#{geo.fetch(:label_x)}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="#{geo.fetch(:label_span)}">#{label}</text>
+                <text x="#{geo.fetch(:label_x)}" y="140" transform="scale(.1)" fill="#fff" textLength="#{geo.fetch(:label_span)}">#{label}</text>
+                <text aria-hidden="true" x="#{geo.fetch(:value_x)}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="#{geo.fetch(:value_span)}">#{value}</text>
+                <text x="#{geo.fetch(:value_x)}" y="140" transform="scale(.1)" fill="#fff" textLength="#{geo.fetch(:value_span)}">#{value}</text>
+              </g>
+            </svg>
+          SVG
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/badge.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+require_relative "coverage_file"
+require_relative "badge/svg"
+
+module SimpleCov
+  module CLI
+    module Badge
+      extend CommandHelpers
+
+      extend self
+
+      TOTAL_KEYS = {line: "lines", branch: "branches", method: "methods"}.freeze
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        key = TOTAL_KEYS[opts.fetch(:criterion)]
+        unless key
+          return error(stderr,
+            "unknown --criterion #{opts.fetch(:criterion).inspect} (expected line, branch, or method)")
+        end
+
+        percent = percent_for(opts, key, stderr)
+        return 1 unless percent
+
+        label = opts.fetch(:label) || "#{opts.fetch(:criterion)} coverage"
+        emit(Svg.render(label: label, percent: percent), opts, stdout)
+      end
+
+      def parse(args)
+        opts = {input: CLI.default_input, criterion: :line,
+                label: nil, output: nil} #: Hash[Symbol, untyped]
+        build_parser do |parser|
+          parser.on("--input PATH") { |v| opts[:input] = v }
+          parser.on("--output PATH") { |v| opts[:output] = v }
+          parser.on("--criterion C") { |v| opts[:criterion] = v.to_sym }
+          parser.on("--label TEXT") { |v| opts[:label] = v }
+        end.parse(args)
+        opts
+      end
+
+      def percent_for(opts, key, stderr)
+        document = CoverageFile.load_document(opts.fetch(:input), command: "badge", stderr: stderr)
+        return nil unless document
+
+        totals = document["total"]
+        percent = totals.dig(key, "percent") if totals.is_a?(Hash)
+        return percent if percent.is_a?(Numeric)
+
+        error_nil(stderr, "no #{opts.fetch(:criterion)} totals in #{opts.fetch(:input)} " \
+                          "(was the run measuring #{opts.fetch(:criterion)} coverage?)")
+      end
+
+      def emit(svg, opts, stdout)
+        opts.fetch(:output) ? File.write(opts.fetch(:output), svg) : stdout.puts(svg)
+        0
+      end
+    end
+  end
+end

data/lib/simplecov/cli/clean.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov clean [--dry-run]`: remove the coverage report directory.
+    # `--dry-run` prints what would be deleted without touching disk.
+    module Clean
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        dir = CLI.coverage_dir
+        return error(stderr, "refusing to remove unsafe coverage directory #{dir.inspect}") unless safe_to_remove?(dir)
+        return announce(stdout, opts, "#{dir} doesn't exist; nothing to do") || 0 unless File.directory?(dir)
+
+        sweep(dir, opts, stdout)
+        0
+      end
+
+      def sweep(dir, opts, stdout)
+        if opts.fetch(:dry_run)
+          announce(stdout, opts, "would remove #{dir} (#{entry_count(dir)} entries)")
+        else
+          FileUtils.rm_rf(dir)
+          announce(stdout, opts, "removed #{dir}")
+        end
+      end
+
+      # FNM_DOTMATCH so the dotfiles rm_rf will actually delete count too. The
+      # glob still yields the directory's own "." entry, which rm_rf does not
+      # remove separately.
+      def entry_count(dir)
+        Dir.glob("#{dir}/**/*", File::FNM_DOTMATCH).count { |path| !path.end_with?("/.") }
+      end
+
+      def announce(stdout, opts, message)
+        stdout.puts("simplecov #{command_name}: #{message}") unless opts.fetch(:quiet)
+      end
+
+      # A filesystem root is its own dirname, on every platform and every Windows
+      # drive. The descendant check only protects roots that happen to contain the
+      # cwd, which misses other drives, so roots are refused outright.
+      def safe_to_remove?(dir)
+        target = canonical_path(dir)
+        return false if File.dirname(target).eql?(target)
+
+        protected_paths.none? { |path| path.eql?(target) || descendant_of?(path, target) }
+      end
+
+      # The working directory, which a coverage directory must not be or contain.
+      # The `.simplecov` project root needs no entry of its own: `Dotfile.find`
+      # walks up from the working directory, so any target containing that root
+      # contains the working directory too.
+      def protected_paths
+        [canonical_path(Dir.pwd)]
+      end
+
+      # Canonical paths only carry a trailing separator on a filesystem root, and
+      # roots are refused before this check runs.
+      def descendant_of?(path, possible_ancestor)
+        path.start_with?("#{possible_ancestor}#{File::SEPARATOR}")
+      end
+
+      def canonical_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def parse(args)
+        opts = {dry_run: false, quiet: false}
+        build_parser do |o|
+          o.on("--dry-run") { opts[:dry_run] = true }
+          quiet_option(o, opts)
+        end.parse(args)
+        opts
+      end
+    end
+  end
+end

data/lib/simplecov/cli/command_helpers.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module SimpleCov
+  module CLI
+    module CommandHelpers
+      STATS_ROW_FORMAT = "  %<label>-7s %<pct>s (%<covered>d / %<total>d)"
+
+      # Raised by the shared --help switch; `CLI.dispatch` turns it into the
+      # command's own slice of the usage text. The explicit handler also overrides
+      # optparse's built-in --help, which would print a bare option summary and
+      # exit the process outright from inside the parser.
+      class HelpRequested < StandardError; end
+
+      def command_name
+        name.split("::").last.downcase
+      end
+
+      def one?(count)
+        (count - 1).zero?
+      end
+
+      def error(stderr, message)
+        stderr.puts("simplecov #{command_name}: #{message}")
+        1
+      end
+
+      # `error` returns 1 for an exit status; query helpers need nil so their
+      # callers can tell "reported" from a real answer.
+      def error_nil(stderr, message)
+        error(stderr, message)
+        nil
+      end
+
+      def recorded_contexts(document, opts, stderr)
+        contexts = document["contexts"]
+        if contexts.nil?
+          return error_nil(stderr, "no test contexts recorded in #{opts.fetch(:input)}. Enable `track_tests` in " \
+                                   "your `SimpleCov.start` block and rerun the suite to record them")
+        end
+        return contexts if contexts.instance_of?(Array) && contexts.all?(String)
+
+        CoverageFile.report_invalid(stderr, command_name, opts.fetch(:input), '"contexts" must be an array of strings')
+      end
+
+      def common_options(parser, opts)
+        parser.on("--input PATH") { |v| opts[:input] = v }
+        parser.on("--json") { opts[:json] = true }
+        parser.on("--no-color") { opts[:no_color] = true }
+      end
+
+      def build_parser
+        OptionParser.new do |parser|
+          yield parser if block_given?
+          on_help(parser)
+        end
+      end
+
+      # mutant:disable
+      # OptionParser answers `-q` as an unambiguous abbreviation of `--quiet`
+      # whether or not the short form is declared.
+      def quiet_option(parser, opts)
+        parser.on("-q", "--quiet") { opts[:quiet] = true }
+      end
+
+      # mutant:disable — optparse matches an abbreviated `-h` against
+      # `--help` whether or not the short form is declared, so dropping
+      # it changes nothing an example could see. Declared anyway, so the
+      # flag appears in the usage text.
+      def on_help(parser)
+        parser.on("--help", "-h") { raise HelpRequested }
+      end
+
+      def parse_common(args, defaults = {})
+        opts = {input: CLI.default_input, json: false, no_color: false} #: Hash[Symbol, untyped]
+        opts.merge!(defaults)
+        rest =
+          build_parser do |parser|
+            common_options(parser, opts)
+            yield parser, opts if block_given?
+          end.parse(args)
+        [opts, rest]
+      end
+
+      def stats_row(label, percent_text, covered, total)
+        format(STATS_ROW_FORMAT, label: "#{label}:", pct: percent_text, covered: covered.to_i, total: total.to_i)
+      end
+    end
+  end
+end

data/lib/simplecov/cli/completions/scripts.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Completions
+      # The per-shell renderers. Each receives the same parsed usage data and
+      # returns the complete script text. The completions command's own shell-name
+      # argument is the one thing the usage tables don't carry, so each renderer
+      # wires it in by hand.
+      module Scripts
+        extend self
+
+        def fish(commands, options)
+          lines = ["# Completions for simplecov. Generated by `simplecov completions fish`."] #: Array[String]
+          commands.each do |name, desc|
+            lines << "complete -c simplecov -f -n __fish_use_subcommand -a #{name} -d #{fish_quote(desc)}"
+          end
+          options.each { |name, list| list.each { |option| lines << fish_option(name, option) } }
+          lines << "complete -c simplecov -f -n '__fish_seen_subcommand_from completions' -a 'fish bash zsh'"
+          lines.join("\n")
+        end
+
+        def fish_option(name, option)
+          parts = ["complete -c simplecov -n '__fish_seen_subcommand_from #{name}'"] #: Array[String]
+          parts << "-s #{(_ = option.fetch(:short)).delete_prefix("-")}" if option.fetch(:short)
+          parts << "-l #{option.fetch(:long).delete_prefix("--")}"
+          parts << "-r" if option.fetch(:arg)
+          parts << "-d #{fish_quote(option.fetch(:desc))}"
+          parts.join(" ")
+        end
+
+        def fish_quote(text)
+          "'#{text.gsub("\\") { "\\\\" }.gsub("'") { "\\'" }}'"
+        end
+
+        BASH_TAIL = [
+          "  esac",
+          '  [[ "$cur" == -* ]] && COMPREPLY=( $(compgen -W "$opts" -- "$cur") )',
+          "}",
+          "complete -o default -F _simplecov simplecov"
+        ].freeze
+
+        def bash(commands, options)
+          (bash_head(commands) + bash_cases(options) + BASH_TAIL).join("\n")
+        end
+
+        def bash_head(commands)
+          [
+            "# Completions for simplecov. Generated by `simplecov completions bash`.",
+            "_simplecov() {",
+            '  local cur="${COMP_WORDS[COMP_CWORD]}" opts=""',
+            '  if [ "$COMP_CWORD" -eq 1 ]; then',
+            "    COMPREPLY=( $(compgen -W \"#{commands.collect(&:first).join(" ")}\" -- \"$cur\") ); return",
+            "  fi",
+            '  case "${COMP_WORDS[1]}" in'
+          ]
+        end
+
+        def bash_cases(options)
+          shells = '    completions) COMPREPLY=( $(compgen -W "fish bash zsh -h --help" -- "$cur") ); return;;'
+          cases = [shells] #: Array[String]
+          options.each do |name, list|
+            next if name.eql?("completions")
+
+            words = list.flat_map { |option| [option.fetch(:short), option.fetch(:long)] }.compact.join(" ")
+            cases << "    #{name}) opts=\"#{words}\";;"
+          end
+          cases
+        end
+
+        ZSH_MIDDLE = [
+          "  )",
+          "  if (( CURRENT == 2 )); then",
+          "    _describe -t commands 'simplecov command' commands",
+          "    return",
+          "  fi",
+          '  case "$words[2]" in'
+        ].freeze
+
+        ZSH_TAIL = ["  esac", "}", '_simplecov "$@"'].freeze
+
+        def zsh(commands, options)
+          head = ["#compdef simplecov", "# Completions for simplecov. Generated by `simplecov completions zsh`.",
+            "_simplecov() {", "  local -a commands", "  commands=("]
+          rows = commands.collect { |name, desc| "    '#{name}:#{zsh_quote(desc)}'" }
+          (head + rows + ZSH_MIDDLE + zsh_cases(options) + ZSH_TAIL).join("\n")
+        end
+
+        def zsh_cases(options)
+          options.collect do |name, list|
+            specs = +""
+            specs << "'1:shell:(fish bash zsh)' " if name.eql?("completions")
+            list.each { |option| zsh_specs(option).each { |spec| specs << spec << " " } }
+            "    #{name}) _arguments #{specs.chop};;"
+          end
+        end
+
+        # `'--input=[desc]'`: the `=` marks an argument-taking switch, which optparse
+        # accepts in that spelling too. Brackets would end the description early, so
+        # they are dropped from it.
+        def zsh_specs(option)
+          desc = "[#{zsh_quote(option.fetch(:desc).delete("[]"))}]"
+          specs = [] #: Array[String]
+          specs << "'#{option.fetch(:short)}#{desc}'" if option.fetch(:short)
+          specs << "'#{option.fetch(:long)}#{"=" if option.fetch(:arg)}#{desc}'"
+        end
+
+        def zsh_quote(text)
+          text.gsub("'") { "'\\''" }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/completions.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+require_relative "usage"
+require_relative "completions/scripts"
+
+module SimpleCov
+  module CLI
+    # `simplecov completions <shell>`: completion scripts for fish, bash, and
+    # zsh, generated from the usage document rather than a hand-kept table, so a
+    # new command or switch shows up in completions the moment it is documented.
+    module Completions
+      extend CommandHelpers
+
+      extend self
+
+      SHELLS = %w[fish bash zsh].freeze
+
+      # "  -q, --quiet               Suppress...": optional short, long, optional
+      # argument placeholder, then the description after the column gap. A single
+      # space never separates the switch from its description, so one non-space
+      # token before a two-space run can only be an argument.
+      OPTION_ROW = /\A\s*(?:(-\w), )?(--[\w-]+)(?: (\S+))?\s{2,}(\S.*)\z/
+      COMMAND_ROW = /\A(\S+)(?: \S+)*?\s{2,}(\S.*)\z/
+
+      def run(args, stdout:, stderr:)
+        shell, = build_parser.parse(args)
+        return error(stderr, "missing shell (expected fish, bash, or zsh)") unless shell
+        unless SHELLS.include?(shell)
+          return error(stderr, "unknown shell #{shell.inspect} (expected fish, bash, or zsh)")
+        end
+
+        stdout.puts(script_for(shell))
+        0
+      end
+
+      def script_for(shell)
+        case shell
+        when "fish" then Scripts.fish(commands, options_by_command)
+        when "bash" then Scripts.bash(commands, options_by_command)
+        else Scripts.zsh(commands, options_by_command)
+        end
+      end
+
+      def commands
+        Usage.text(CLI).split("\n\n").fetch(1).lines.filter_map do |row|
+          match = row.strip.match(COMMAND_ROW)
+          match && [(_ = match[1]), (_ = match[2])]
+        end
+      end
+
+      def options_by_command
+        commands.filter_map do |name, _desc|
+          list = options_for(name)
+          [name, list] unless list.empty?
+        end.to_h
+      end
+
+      # `run` takes no options of its own, since everything after it belongs to the
+      # command being run, so it must not even offer --help.
+      def options_for(command)
+        return [] if command.eql?("run")
+
+        sections = Usage.text(CLI).split("\n\n").select { |section| Usage.section_for?(section, command) }
+        options = sections.flat_map { |section| section_options(section) }
+        options << {short: "-h", long: "--help", arg: nil, desc: "Show this command's usage"}
+      end
+
+      # Rows that don't parse as options are continuations of the previous row's
+      # description, wrapped for the terminal.
+      def section_options(section)
+        section.lines.each_with_object([]) do |line, options|
+          if (match = line.chomp.match(OPTION_ROW))
+            options << {short: match[1], long: match[2], arg: match[3], desc: (_ = match[4])}
+          elsif (previous = options.last)
+            previous[:desc] = "#{previous.fetch(:desc)} #{line.strip}"
+          end
+        end
+      end
+    end
+  end
+end