Generate bash completions automatically

Library/Homebrew/cli/parser.rb

@@ -16,7 +16,7 @@ module Homebrew
     class Parser
       extend T::Sig
 
-      attr_reader :processed_options, :hide_from_man_page
+      attr_reader :processed_options, :hide_from_man_page, :named_args_type
 
       def self.from_cmd_path(cmd_path)
         cmd_args_method_name = Commands.args_method_name(cmd_path)
@@ -539,6 +539,7 @@ module Homebrew
 
       def process_option(*args)
         option, = @parser.make_switch(args)
+        @processed_options.reject! { |existing| option.long.first.present? && existing.second == option.long.first }
         @processed_options << [option.short.first, option.long.first, option.arg, option.desc.first]
       end
 

Library/Homebrew/cmd/options.rb

@@ -3,8 +3,6 @@
 
 require "formula"
 require "options"
-require "cli/parser"
-require "commands"
 
 module Homebrew
   extend T::Sig
@@ -42,15 +40,7 @@ module Homebrew
     elsif args.installed?
       puts_options Formula.installed.sort, args: args
     elsif !args.command.nil?
-      path = Commands.path(args.command)
-      odie "Unknown command: #{args.command}" unless path
-      cmd_options = if cmd_parser = CLI::Parser.from_cmd_path(path)
-        cmd_parser.processed_options.map do |short, long, _, desc|
-          [long || short, desc]
-        end
-      else
-        cmd_comment_options(path)
-      end
+      cmd_options = Commands.command_options(args.command)
       if args.compact?
         puts cmd_options.sort.map(&:first) * " "
       else
@@ -64,20 +54,6 @@ module Homebrew
     end
   end
 
-  def cmd_comment_options(cmd_path)
-    options = []
-    comment_lines = cmd_path.read.lines.grep(/^#:/)
-    return options if comment_lines.empty?
-
-    # skip the comment's initial usage summary lines
-    comment_lines.slice(2..-1).each do |line|
-      if / (?<option>-[-\w]+) +(?<desc>.*)$/ =~ line
-        options << [option, desc]
-      end
-    end
-    options
-  end
-
   def puts_options(formulae, args:)
     formulae.each do |f|
       next if f.options.empty?

Library/Homebrew/cmd/upgrade.rb

@@ -90,7 +90,7 @@ module Homebrew
 
       conflicts "--build-from-source", "--force-bottle"
 
-      named_args [:installed_formula, :installed_cask]
+      named_args [:outdated_formula, :outdated_cask]
     end
   end
 

Library/Homebrew/commands.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "cask/cmd"
+require "completions"
 
 # Helper functions for commands.
 #
@@ -91,10 +92,10 @@ module Commands
     path
   end
 
-  def commands(aliases: false)
+  def commands(external: true, aliases: false)
     cmds = internal_commands
     cmds += internal_developer_commands
-    cmds += external_commands
+    cmds += external_commands if external
     cmds += internal_commands_aliases if aliases
     cmds += cask_commands(aliases: aliases).map { |cmd| "cask #{cmd}" }
     cmds.sort
@@ -185,6 +186,7 @@ module Commands
 
   def rebuild_internal_commands_completion_list
     cmds = internal_commands + internal_developer_commands + internal_commands_aliases
+    cmds.reject! { |cmd| Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include? cmd }
 
     file = HOMEBREW_REPOSITORY/"completions/internal_commands_list.txt"
     file.atomic_write("#{cmds.sort.join("\n")}\n")
@@ -194,7 +196,45 @@ module Commands
     # Ensure that the cache exists so we can build the commands list
     HOMEBREW_CACHE.mkpath
 
+    cmds = commands(aliases: true).reject do |cmd|
+      # TODO: remove the cask check when `brew cask` is removed
+      cmd.start_with?("cask ") || Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include?(cmd)
+    end
+
     file = HOMEBREW_CACHE/"all_commands_list.txt"
-    file.atomic_write("#{commands(aliases: true).sort.join("\n")}\n")
+    file.atomic_write("#{cmds.sort.join("\n")}\n")
+  end
+
+  def command_options(command)
+    path = Commands.path(command)
+    return unless path
+
+    if cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
+      cmd_parser.processed_options.map do |short, long, _, desc|
+        [long || short, desc]
+      end
+    else
+      options = []
+      comment_lines = path.read.lines.grep(/^#:/)
+      return options if comment_lines.empty?
+
+      # skip the comment's initial usage summary lines
+      comment_lines.slice(2..-1).each do |line|
+        if / (?<option>-[-\w]+) +(?<desc>.*)$/ =~ line
+          options << [option, desc]
+        end
+      end
+      options
+    end
+  end
+
+  def named_args_type(command)
+    path = Commands.path(command)
+    return unless path
+
+    cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
+    return if cmd_parser.blank?
+
+    Array(cmd_parser.named_args_type)
   end
 end

Library/Homebrew/completions.rb

@@ -3,6 +3,7 @@
 
 require "utils/link"
 require "settings"
+require "erb"
 
 module Homebrew
   # Helper functions for generating shell completions.
@@ -13,7 +14,28 @@ module Homebrew
 
     module_function
 
+    COMPLETIONS_DIR = (HOMEBREW_REPOSITORY/"completions").freeze
+    TEMPLATE_DIR = (HOMEBREW_LIBRARY_PATH/"completions").freeze
+
     SHELLS = %w[bash fish zsh].freeze
+    COMPLETIONS_EXCLUSION_LIST = %w[
+      instal
+      uninstal
+      update-report
+    ].freeze
+
+    BASH_NAMED_ARGS_COMPLETION_FUNCTION_MAPPING = {
+      formula:           "__brew_complete_formulae",
+      installed_formula: "__brew_complete_installed_formulae",
+      outdated_formula:  "__brew_complete_outdated_formulae",
+      cask:              "__brew_complete_casks",
+      installed_cask:    "__brew_complete_installed_casks",
+      outdated_cask:     "__brew_complete_outdated_casks",
+      tap:               "__brew_complete_tapped",
+      installed_tap:     "__brew_complete_tapped",
+      command:           "__brew_complete_commands",
+      diagnostic_check:  '__brewcomp "$(brew doctor --list-checks)"',
+    }.freeze
 
     sig { void }
     def link!
@@ -65,5 +87,85 @@ module Homebrew
 
       Settings.write :completionsmessageshown, true
     end
+
+    sig { void }
+    def update_shell_completions!
+      commands = Commands.commands(external: false, aliases: true).sort
+
+      (COMPLETIONS_DIR/"bash/brew").atomic_write generate_bash_completion_file(commands)
+    end
+
+    sig { params(command: String).returns(T::Boolean) }
+    def command_gets_completions?(command)
+      return false if command.start_with? "cask " # TODO: remove when `brew cask` commands are removed
+
+      command_options(command).any?
+    end
+
+    sig { params(command: String).returns(T::Array[String]) }
+    def command_options(command)
+      options = []
+      Commands.command_options(command)&.each do |option|
+        next if option.blank?
+
+        name = option.first
+        if name.start_with? "--[no-]"
+          options << name.remove("[no-]")
+          options << name.sub("[no-]", "no-")
+        else
+          options << name
+        end
+      end&.compact
+      options.sort
+    end
+
+    sig { params(command: String).returns(T.nilable(String)) }
+    def generate_bash_subcommand_completion(command)
+      return unless command_gets_completions? command
+
+      named_completion_string = ""
+      if types = Commands.named_args_type(command)
+        named_args_strings, named_args_types = types.partition { |type| type.is_a? String }
+
+        named_args_types.each do |type|
+          next unless BASH_NAMED_ARGS_COMPLETION_FUNCTION_MAPPING.key? type
+
+          named_completion_string += "\n  #{BASH_NAMED_ARGS_COMPLETION_FUNCTION_MAPPING[type]}"
+        end
+
+        named_completion_string += "\n  __brewcomp \"#{named_args_strings.join(" ")}\"" if named_args_strings.any?
+      end
+
+      <<~COMPLETION
+        _brew_#{Commands.method_name command}() {
+          local cur="${COMP_WORDS[COMP_CWORD]}"
+          case "$cur" in
+            -*)
+              __brewcomp "
+              #{command_options(command).join("\n      ")}
+              "
+              return
+              ;;
+          esac#{named_completion_string}
+        }
+      COMPLETION
+    end
+
+    sig { params(commands: T::Array[String]).returns(T.nilable(String)) }
+    def generate_bash_completion_file(commands)
+      variables = OpenStruct.new
+
+      variables[:completion_functions] = commands.map do |command|
+        generate_bash_subcommand_completion command
+      end.compact
+
+      variables[:function_mappings] = commands.map do |command|
+        next unless command_gets_completions? command
+
+        "#{command}) _brew_#{Commands.method_name command} ;;"
+      end.compact
+
+      ERB.new((TEMPLATE_DIR/"bash.erb").read, trim_mode: ">").result(variables.instance_eval { binding })
+    end
   end
 end

Library/Homebrew/completions/bash.erb

@@ -0,0 +1,167 @@
+<%
+# To make changes to the completions:
+#
+# - For changes to a command under `COMMANDS` or `DEVELOPER COMMANDS` sections):
+#   - Find the source file in `Library/Homebrew/[dev-]cmd/<command>.{rb,sh}`.
+#   - For `.rb` files, edit the `<command>_args` method.
+#   - For `.sh` files, edit the top comment, being sure to use the line prefix
+#     `#:` for the comments to be recognized as documentation. If in doubt,
+#     compare with already documented commands.
+# - For other changes: Edit this file.
+#
+# When done, regenerate the completions by running `brew man`.
+%>
+# Bash completion script for brew(1)
+
+# Indicates there are no completions
+__brewcomp_null() {
+  COMPREPLY=""
+}
+
+__brewcomp_words_include() {
+  local i=1
+  while [[ "$i" -lt "$COMP_CWORD" ]]
+  do
+    if [[ "${COMP_WORDS[i]}" = "$1" ]]
+    then
+      return 0
+    fi
+    (( i++ ))
+  done
+  return 1
+}
+
+# Find the previous non-switch word
+__brewcomp_prev() {
+  local idx="$((COMP_CWORD - 1))"
+  local prv="${COMP_WORDS[idx]}"
+  while [[ "$prv" = -* ]]
+  do
+    (( idx-- ))
+    prv="${COMP_WORDS[idx]}"
+  done
+  echo "$prv"
+}
+
+__brewcomp() {
+  # break $1 on space, tab, and newline characters,
+  # and turn it into a newline separated list of words
+  local list s sep=$'\n' IFS=$' \t\n'
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+
+  for s in $1
+  do
+    __brewcomp_words_include "$s" && continue
+    list="$list$s$sep"
+  done
+
+  IFS="$sep"
+  COMPREPLY=($(compgen -W "$list" -- "$cur"))
+}
+
+# Don't use __brewcomp() in any of the __brew_complete_foo functions, as
+# it is too slow and is not worth it just for duplicate elimination.
+__brew_complete_formulae() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local formulae="$(brew formulae)"
+  COMPREPLY=($(compgen -W "$formulae" -- "$cur"))
+}
+
+__brew_complete_casks() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local casks="$(brew casks)"
+  COMPREPLY=($(compgen -W "$casks" -- "$cur"))
+}
+
+__brew_complete_installed_formulae() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local installed_formulae="$(command ls "$(brew --cellar)" 2>/dev/null)"
+  COMPREPLY=($(compgen -W "$installed_formulae" -- "$cur"))
+}
+
+__brew_complete_installed_casks() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local installed_casks="$(command ls "$(brew --caskroom)" 2>/dev/null)"
+  COMPREPLY=($(compgen -W "$installed_casks" -- "$cur"))
+}
+
+__brew_complete_outdated_formulae() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local outdated_formulae="$(brew outdated --formula --quiet)"
+  COMPREPLY=($(compgen -W "$outdated_formulae" -- "$cur"))
+}
+
+__brew_complete_outdated_casks() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local outdated_casks="$(brew outdated --cask --quiet)"
+  COMPREPLY=($(compgen -W "$outdated_casks" -- "$cur"))
+}
+
+__brew_complete_tapped() {
+  local taplib="$(brew --repository)/Library/Taps"
+  local dir taps
+
+  for dir in "$taplib"/*/*
+  do
+    [[ -d "$dir" ]] || continue
+    dir="${dir#${taplib}/}"
+    dir="${dir/homebrew-/}"
+    taps="$taps $dir"
+  done
+  __brewcomp "$taps"
+}
+
+__brew_complete_commands() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  HOMEBREW_CACHE=$(brew --cache)
+  HOMEBREW_REPOSITORY=$(brew --repo)
+  # Do not auto-complete "*instal" or "*uninstal" aliases for "*install" commands.
+  [[ -f "$HOMEBREW_CACHE/all_commands_list.txt" ]] &&
+    local cmds="$(cat "$HOMEBREW_CACHE/all_commands_list.txt" | \grep -v instal$)" ||
+    local cmds="$(cat "$HOMEBREW_REPOSITORY/completions/internal_commands_list.txt" | \grep -v instal$)"
+  COMPREPLY=($(compgen -W "$cmds" -- "$cur"))
+}
+
+<%= completion_functions.join("\n") %>
+
+_brew() {
+  local i=1 cmd
+
+  # find the subcommand
+  while [[ "$i" -lt "$COMP_CWORD" ]]
+  do
+    local s="${COMP_WORDS[i]}"
+    case "$s" in
+      --*)
+        cmd="$s"
+        break
+        ;;
+      -*)
+        ;;
+      *)
+        cmd="$s"
+        break
+        ;;
+    esac
+    (( i++ ))
+  done
+
+  if [[ "$i" -eq "$COMP_CWORD" ]]
+  then
+    __brew_complete_commands
+    return
+  fi
+
+  # subcommands have their own completion functions
+  case "$cmd" in
+    <%= function_mappings.join("\n    ").concat("\n") %>
+    *) ;;
+  esac
+}
+
+# keep around for compatibility
+_brew_to_completion() {
+  _brew
+}
+
+complete -o bashdefault -o default -F _brew brew

Library/Homebrew/dev-cmd/man.rb

@@ -5,6 +5,7 @@ require "formula"
 require "erb"
 require "ostruct"
 require "cli/parser"
+require "completions"
 
 module Homebrew
   extend T::Sig
@@ -42,6 +43,7 @@ module Homebrew
 
     Commands.rebuild_internal_commands_completion_list
     regenerate_man_pages(preserve_date: args.fail_if_changed?, quiet: args.quiet?)
+    Completions.update_shell_completions!
 
     diff = system_command "git", args: [
       "-C", HOMEBREW_REPOSITORY, "diff", "--exit-code", "docs/Manpage.md", "manpages", "completions"

completions/internal_commands_list.txt

@@ -46,7 +46,6 @@ help
 home
 homepage
 info
-instal
 install
 install-bundler-gems
 irb
@@ -92,7 +91,6 @@ test
 tests
 typecheck
 unbottled
-uninstal
 uninstall
 unlink
 unpack
@@ -102,7 +100,6 @@ up
 update
 update-license-data
 update-python-resources
-update-report
 update-reset
 update-test
 upgrade