Merge pull request #21781 from mvanhorn/osc/21482-feat-cask-shell-completions

cask: add generate_completions_from_executable DSL artifact

Author: MikeMcQuaid

Library/Homebrew/cask/artifact.rb

@@ -24,6 +24,7 @@
 require "cask/artifact/screen_saver"
 require "cask/artifact/bashcompletion"
 require "cask/artifact/fishcompletion"
+require "cask/artifact/generated_completion"
 require "cask/artifact/zshcompletion"
 require "cask/artifact/service"
 require "cask/artifact/stage_only"

Library/Homebrew/cask/artifact/generated_completion.rb

@@ -0,0 +1,154 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "cask/artifact/abstract_artifact"
+require "cask/artifact/bashcompletion"
+require "cask/artifact/fishcompletion"
+require "cask/artifact/zshcompletion"
+require "extend/hash/keys"
+require "utils/shell_completion"
+
+module Cask
+  module Artifact
+    # Artifact corresponding to the `generate_completions_from_executable` stanza.
+    class GeneratedCompletion < AbstractArtifact
+      SUPPORTED_SHELLS = T.let([:bash, :zsh, :fish, :pwsh].freeze, T::Array[Symbol])
+
+      sig { override.returns(Symbol) }
+      def self.dsl_key
+        :generate_completions_from_executable
+      end
+
+      sig {
+        params(
+          cask:                   Cask,
+          args:                   T.any(Pathname, String),
+          base_name:              T.nilable(String),
+          shell_parameter_format: T.nilable(T.any(Symbol, String)),
+          shells:                 T.nilable(T::Array[Symbol]),
+        ).returns(T.attached_class)
+      }
+      def self.from_args(cask, *args, base_name: nil, shell_parameter_format: nil, shells: nil)
+        raise CaskInvalidError.new(cask.token, "'#{dsl_key}' requires at least one command") if args.empty?
+
+        commands = args.to_a
+        resolved_shells = shells || ::Utils::ShellCompletion.default_completion_shells(shell_parameter_format)
+
+        unsupported_shells = resolved_shells - SUPPORTED_SHELLS
+        unless unsupported_shells.empty?
+          raise CaskInvalidError.new(
+            cask.token,
+            "'#{dsl_key}' does not support shell(s): #{unsupported_shells.join(", ")}",
+          )
+        end
+
+        new(
+          cask,
+          commands,
+          base_name:,
+          shell_parameter_format:,
+          shells:                 resolved_shells,
+        )
+      end
+
+      sig {
+        params(
+          cask:                   Cask,
+          commands:               T::Array[T.any(Pathname, String)],
+          base_name:              T.nilable(String),
+          shell_parameter_format: T.nilable(T.any(Symbol, String)),
+          shells:                 T::Array[Symbol],
+        ).void
+      }
+      def initialize(cask, commands, base_name:, shell_parameter_format:, shells:)
+        super(cask, *commands, base_name:, shell_parameter_format:, shells:)
+
+        @commands = T.let(commands, T::Array[T.any(Pathname, String)])
+        @base_name = T.let(base_name, T.nilable(String))
+        @shell_parameter_format = T.let(shell_parameter_format, T.nilable(T.any(Symbol, String)))
+        @shells = T.let(shells, T::Array[Symbol])
+        @resolved_base_name = T.let(nil, T.nilable(String))
+      end
+
+      sig { returns(T::Array[T.any(Pathname, String)]) }
+      attr_reader :commands
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :base_name
+
+      sig { returns(T.nilable(T.any(Symbol, String))) }
+      attr_reader :shell_parameter_format
+
+      sig { returns(T::Array[Symbol]) }
+      attr_reader :shells
+
+      sig { override.returns(String) }
+      def summarize
+        "#{commands.join(" ")} (base_name: #{resolved_base_name}, shells: #{shells.join(", ")})"
+      end
+
+      sig { params(_options: T.untyped).void }
+      def install_phase(**_options)
+        executable = staged_path_join_executable(T.must(commands.first))
+
+        shells.each do |shell|
+          popen_read_env = { "SHELL" => shell.to_s }
+          shell_parameter = ::Utils::ShellCompletion.completion_shell_parameter(
+            shell_parameter_format, shell, executable.to_s, popen_read_env
+          )
+
+          script_path = completion_script_path(shell)
+          script_path.dirname.mkpath
+          script_path.write(::Utils::ShellCompletion.generate_completion_output(
+                              [executable, *commands[1..]],
+                              shell_parameter,
+                              popen_read_env,
+                            ))
+        rescue => e
+          opoo "Failed to generate #{shell} completions from #{executable}: #{e}"
+        end
+      end
+
+      sig { params(command: T.class_of(SystemCommand), _options: T.untyped).void }
+      def uninstall_phase(command: SystemCommand, **_options)
+        shells.each do |shell|
+          path = completion_script_path(shell)
+          next unless path.exist?
+
+          Utils.gain_permissions_remove(path, command:)
+        rescue => e
+          opoo "Failed to remove #{shell} generated completions: #{e}"
+        end
+      end
+
+      private
+
+      sig { returns(String) }
+      def resolved_base_name
+        @resolved_base_name ||= T.let(begin
+          executable = staged_path_join_executable(T.must(commands.first))
+          name = base_name || File.basename(executable.to_s)
+          name = cask.token if name.empty?
+          name
+        end, T.nilable(String))
+        @resolved_base_name
+      end
+
+      sig { params(shell: Symbol).returns(Pathname) }
+      def completion_script_path(shell)
+        case shell
+        when :bash
+          BashCompletion.new(cask, resolved_base_name).resolve_target(resolved_base_name)
+        when :zsh
+          ZshCompletion.new(cask, resolved_base_name).resolve_target(resolved_base_name)
+        when :fish
+          FishCompletion.new(cask, resolved_base_name).resolve_target(resolved_base_name)
+        when :pwsh
+          HOMEBREW_PREFIX/"share/pwsh/completions"/"_#{resolved_base_name}.ps1"
+        else
+          raise ArgumentError, "unsupported shell: #{shell}"
+        end
+      end
+    end
+  end
+end

Library/Homebrew/cask/dsl.rb

@@ -61,6 +61,7 @@ class DSL
       Artifact::ZshCompletion,
       Artifact::FishCompletion,
       Artifact::BashCompletion,
+      Artifact::GeneratedCompletion,
       Artifact::Uninstall,
       Artifact::Zap,
     ].freeze

Library/Homebrew/cask/installer.rb

@@ -333,6 +333,7 @@ def install_artifacts(predecessor: nil)
           artifact,
           T.any(
             Artifact::AbstractFlightBlock,
+            Artifact::GeneratedCompletion,
             Artifact::Installer,
             Artifact::KeyboardLayout,
             Artifact::Mdimporter,
@@ -600,6 +601,7 @@ def uninstall_artifacts(clear: false, successor: nil)
             artifact,
             T.any(
               Artifact::AbstractFlightBlock,
+              Artifact::GeneratedCompletion,
               Artifact::KeyboardLayout,
               Artifact::Moved,
               Artifact::Qlplugin,

Library/Homebrew/formula.rb

@@ -14,6 +14,7 @@
 require "utils/inreplace"
 require "utils/shebang"
 require "utils/shell"
+require "utils/shell_completion"
 require "utils/git_repository"
 require "build_environment"
 require "build_options"
@@ -2407,7 +2408,7 @@ def extract_macho_slice_from(file, arch = Hardware::CPU.arch)
   def generate_completions_from_executable(*commands,
                                            base_name: nil,
                                            shell_parameter_format: nil,
-                                           shells: default_completion_shells(shell_parameter_format))
+                                           shells: Utils::ShellCompletion.default_completion_shells(shell_parameter_format))
     executable = commands.first.to_s
     base_name ||= File.basename(executable) if executable.start_with?(bin.to_s, sbin.to_s)
     base_name ||= name
@@ -2423,75 +2424,17 @@ def generate_completions_from_executable(*commands,
       popen_read_env = { "SHELL" => shell.to_s }
       script_path = completion_script_path_map[shell]
 
-      shell_parameter = completion_shell_parameter(
+      shell_parameter = Utils::ShellCompletion.completion_shell_parameter(
         shell_parameter_format,
         shell,
         executable,
         popen_read_env,
       )
 
-      popen_read_args = %w[]
-      popen_read_args << commands
-      popen_read_args << shell_parameter if shell_parameter.present?
-      popen_read_args.flatten!
-
-      popen_read_options = {}
-      popen_read_options[:err] = :err unless ENV["HOMEBREW_STDERR"]
-
       script_path.dirname.mkpath
-      script_path.write Utils.safe_popen_read(popen_read_env, *popen_read_args, **popen_read_options)
-    end
-  end
-
-  sig { params(format: T.nilable(T.any(Symbol, String))).returns(T::Array[Symbol]) }
-  def default_completion_shells(format)
-    case format
-    when :cobra, :typer
-      [:bash, :zsh, :fish, :pwsh]
-    else
-      [:bash, :zsh, :fish]
-    end
-  end
-  private :default_completion_shells
-
-  sig {
-    params(
-      format:     T.nilable(T.any(Symbol, String)),
-      shell:      Symbol,
-      executable: String,
-      env:        T::Hash[String, String],
-    ).returns(T.nilable(T.any(String, T::Array[String])))
-  }
-  def completion_shell_parameter(format, shell, executable, env)
-    # Go's cobra and Rust's clap accept "powershell".
-    shell_parameter = (shell == :pwsh) ? "powershell" : shell.to_s
-
-    case format
-    when nil
-      shell_parameter
-    when :arg
-      "--shell=#{shell_parameter}"
-    when :clap
-      env["COMPLETE"] = shell_parameter
-      nil
-    when :click
-      prog_name = File.basename(executable).upcase.tr("-", "_")
-      env["_#{prog_name}_COMPLETE"] = "#{shell_parameter}_source"
-      nil
-    when :cobra
-      ["completion", shell_parameter]
-    when :flag
-      "--#{shell_parameter}"
-    when :none
-      nil
-    when :typer
-      env["_TYPER_COMPLETE_TEST_DISABLE_SHELL_DETECTION"] = "1"
-      ["--show-completion", shell_parameter]
-    else
-      "#{format}#{shell}"
+      script_path.write Utils::ShellCompletion.generate_completion_output(commands, shell_parameter, popen_read_env)
     end
   end
-  private :completion_shell_parameter
 
   # An array of all core {Formula} names.
   sig { returns(T::Array[String]) }

Library/Homebrew/test/cask/artifact/generated_completion_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+RSpec.describe Cask::Artifact::GeneratedCompletion, :cask do
+  let(:staged_path) { Pathname(Dir.mktmpdir) }
+
+  let(:cask) do
+    tmp_staged = staged_path
+    Cask::Cask.new("test-generated-completion") do
+      version "1.0"
+      sha256 :no_check
+      url "file:///dev/null"
+      generate_completions_from_executable "bin/foo", "completions"
+      instance_variable_set(:@staged_path, tmp_staged)
+    end
+  end
+
+  let(:bash_dir) { cask.config.bash_completion }
+  let(:zsh_dir) { cask.config.zsh_completion }
+  let(:fish_dir) { cask.config.fish_completion }
+
+  before do
+    (staged_path/"bin").mkpath
+    (staged_path/"bin/foo").write("#!/bin/sh\necho \"$SHELL completion\"")
+    (staged_path/"bin/foo").chmod(0755)
+  end
+
+  after do
+    FileUtils.rm_rf(staged_path)
+  end
+
+  describe "#install_phase" do
+    it "generates completion scripts for default shells" do
+      artifact = cask.artifacts.grep(described_class).first
+
+      allow(Utils).to receive(:safe_popen_read) do |env, *_args, **_opts|
+        "#{env.fetch("SHELL")} completion output"
+      end
+
+      artifact.install_phase
+
+      expect(bash_dir/"foo").to be_a_file
+      expect((bash_dir/"foo").read).to eq("bash completion output")
+      expect(zsh_dir/"_foo").to be_a_file
+      expect((zsh_dir/"_foo").read).to eq("zsh completion output")
+      expect(fish_dir/"foo.fish").to be_a_file
+      expect((fish_dir/"foo.fish").read).to eq("fish completion output")
+    end
+
+    context "when generation fails for one shell" do
+      it "warns and continues generating other shells" do
+        artifact = cask.artifacts.grep(described_class).first
+
+        allow(Utils).to receive(:safe_popen_read) do |env, *_args, **_opts|
+          raise "boom" if env.fetch("SHELL") == "bash"
+
+          "zsh completion"
+        end
+
+        expect { artifact.install_phase }
+          .to output(/Failed to generate bash completions/).to_stderr
+
+        expect(zsh_dir/"_foo").to be_a_file
+      end
+    end
+  end
+
+  describe "#uninstall_phase" do
+    it "removes generated completion scripts" do
+      artifact = cask.artifacts.grep(described_class).first
+
+      bash_dir.mkpath
+      zsh_dir.mkpath
+      fish_dir.mkpath
+      (bash_dir/"foo").write("bash")
+      (zsh_dir/"_foo").write("zsh")
+      (fish_dir/"foo.fish").write("fish")
+
+      artifact.uninstall_phase(command: NeverSudoSystemCommand)
+
+      expect(bash_dir/"foo").not_to exist
+      expect(zsh_dir/"_foo").not_to exist
+      expect(fish_dir/"foo.fish").not_to exist
+    end
+  end
+
+  context "with specific shells and format" do
+    let(:cask) do
+      tmp_staged = staged_path
+      Cask::Cask.new("test-generated-completion") do
+        version "1.0"
+        sha256 :no_check
+        url "file:///dev/null"
+        generate_completions_from_executable "bin/foo", "completions",
+                                             shells: [:zsh], shell_parameter_format: :arg, base_name: "bar"
+        instance_variable_set(:@staged_path, tmp_staged)
+      end
+    end
+
+    it "generates only for the specified shell with the correct format" do
+      artifact = cask.artifacts.grep(described_class).first
+      captured_args = nil
+
+      allow(Utils).to receive(:safe_popen_read) do |_env, *args, **_opts|
+        captured_args = args
+        "zsh completion"
+      end
+
+      artifact.install_phase
+
+      expect(captured_args).to include("--shell=zsh")
+      expect(zsh_dir/"_bar").to be_a_file
+      expect(bash_dir/"bar").not_to exist
+      expect(fish_dir/"bar.fish").not_to exist
+    end
+  end
+end