cask/reinstall: Support --zap for entirely purging cask files

- The `brew uninstall` command has `--zap`, so let's make `brew
  reinstall` have parity here for a better user experience. (Requested
  in issue 12983.)
- It feels weird that to get my new reinstall test to pass I had to add
  `--zap` to `cask/cmd/install.rb`, not `cask/cmd/reinstall.rb` to get
  the tests to pass. But the `brew reinstall --cask caffeine --zap`
  command worked fine all the time. The CLI argument parser from the
  test run was complaining about not knowing what `zap` was. As a
  result, `--zap` now shows up as a switch in `brew install --help`
  which I'm not 100% convinced is the desired UX. But I've edited the
  description accordingly to specify that it will only work on
  `reinstall` operations (and `--zap` on `install` is a no-op).

```
issyl0 at pictor in /opt/homebrew on reinstall-cask-zap
❯ brew reinstall --cask caffeine --zap
==> Downloading https://github.com/IntelliScape/caffeine/releases/download/1.1.3/Caffeine.dmg
Already downloaded: /Users/issyl0/Library/Caches/Homebrew/downloads/3d6ccfdd3b8d0ab37d1c2468d6e69078c2d31d3b12bf51947c4db21e5f376af2--Caffeine.dmg
==> Implied `brew uninstall --cask caffeine`
==> Backing App 'Caffeine.app' up to '/opt/homebrew/Caskroom/caffeine/1.1.3/Caffeine.app'
==> Removing App '/Applications/Caffeine.app'
==> Dispatching zap stanza
==> Trashing files:
~/Library/Application Support/com.intelliscapesolutions.caffeine
~/Library/Preferences/com.intelliscapesolutions.caffeine.plist
~/Library/Caches/com.intelliscapesolutions.caffeine
~/Library/HTTPStoages/com.intelliscapesolutions.caffeine.binarycookies
==> Removing all staged versions of Cask 'caffeine'
==> Installing Cask caffeine
==> Moving App 'Caffeine.app' to '/Applications/Caffeine.app'
🍺  caffeine was successfully installed!
```

Library/Homebrew/cask/cmd/install.rb

@@ -13,6 +13,10 @@ module Cask
         [:switch, "--skip-cask-deps", {
           description: "Skip installing cask dependencies.",
         }],
+        [:switch, "--zap", {
+          description: "For use with `brew reinstall --cask`. Remove all files associated with a cask. " \
+                       "*May remove files which are shared between applications.*",
+        }],
       ].freeze
 
       def self.parser(&block)
@@ -39,6 +43,7 @@ module Cask
           require_sha:    args.require_sha?,
           quarantine:     args.quarantine?,
           quiet:          args.quiet?,
+          zap:            args.zap?,
         )
       end
 
@@ -50,7 +55,8 @@ module Cask
         skip_cask_deps: nil,
         require_sha: nil,
         quarantine: nil,
-        quiet: nil
+        quiet: nil,
+        zap: nil
       )
         odie "Installing casks is supported only on macOS" unless OS.mac?
 
@@ -61,6 +67,7 @@ module Cask
           skip_cask_deps: skip_cask_deps,
           require_sha:    require_sha,
           quarantine:     quarantine,
+          zap:            zap,
         }.compact
 
         options[:quarantine] = true if options[:quarantine].nil?

Library/Homebrew/cask/cmd/reinstall.rb

@@ -19,6 +19,7 @@ module Cask
           skip_cask_deps: args.skip_cask_deps?,
           require_sha:    args.require_sha?,
           quarantine:     args.quarantine?,
+          zap:            args.zap?,
         )
       end
 
@@ -29,7 +30,8 @@ module Cask
         skip_cask_deps: nil,
         binaries: nil,
         require_sha: nil,
-        quarantine: nil
+        quarantine: nil,
+        zap: nil
       )
         require "cask/installer"
 
@@ -40,6 +42,7 @@ module Cask
           skip_cask_deps: skip_cask_deps,
           require_sha:    require_sha,
           quarantine:     quarantine,
+          zap:            zap,
         }.compact
 
         options[:quarantine] = true if options[:quarantine].nil?

Library/Homebrew/cask/installer.rb

@@ -29,7 +29,7 @@ module Cask
 
     def initialize(cask, command: SystemCommand, force: false,
                    skip_cask_deps: false, binaries: true, verbose: false,
-                   require_sha: false, upgrade: false,
+                   zap: false, require_sha: false, upgrade: false,
                    installed_as_dependency: false, quarantine: true,
                    verify_download_integrity: true, quiet: false)
       @cask = cask
@@ -38,6 +38,7 @@ module Cask
       @skip_cask_deps = skip_cask_deps
       @binaries = binaries
       @verbose = verbose
+      @zap = zap
       @require_sha = require_sha
       @reinstall = false
       @upgrade = upgrade
@@ -48,7 +49,7 @@ module Cask
     end
 
     attr_predicate :binaries?, :force?, :skip_cask_deps?, :require_sha?,
-                   :reinstall?, :upgrade?, :verbose?, :installed_as_dependency?,
+                   :reinstall?, :upgrade?, :verbose?, :zap?, :installed_as_dependency?,
                    :quarantine?, :quiet?
 
     def self.caveats(cask)
@@ -157,7 +158,8 @@ module Cask
       installed_cask = installed_caskfile.exist? ? CaskLoader.load(installed_caskfile) : @cask
 
       # Always force uninstallation, ignore method parameter
-      Installer.new(installed_cask, verbose: verbose?, force: true, upgrade: upgrade?).uninstall
+      cask_installer = Installer.new(installed_cask, verbose: verbose?, force: true, upgrade: upgrade?)
+      zap? ? cask_installer.zap : cask_installer.uninstall
     end
 
     sig { returns(String) }

Library/Homebrew/cmd/reinstall.rb

@@ -159,6 +159,7 @@ module Homebrew
         require_sha:    args.require_sha?,
         skip_cask_deps: args.skip_cask_deps?,
         quarantine:     args.quarantine?,
+        zap:            args.zap?,
       )
     end
 

Library/Homebrew/test/cask/cmd/list_spec.rb

@@ -108,7 +108,12 @@ describe Cask::Cmd::List, :cask do
             "artifacts": [
               [
                 "Caffeine.app"
-              ]
+              ],
+              {
+                "trash": "$HOME/support/fixtures/cask/caffeine/org.example.caffeine.plist",
+                "signal": {
+                }
+              }
             ],
             "caveats": null,
             "depends_on": {

Library/Homebrew/test/cask/cmd/reinstall_spec.rb

@@ -24,6 +24,31 @@ describe Cask::Cmd::Reinstall, :cask do
     }.to output(output).to_stdout
   end
 
+  it "displays the reinstallation progress with zapping" do
+    caffeine = Cask::CaskLoader.load(cask_path("local-caffeine"))
+
+    Cask::Installer.new(caffeine).install
+
+    output = Regexp.new <<~EOS
+      ==> Downloading file:.*caffeine.zip
+      Already downloaded: .*--caffeine.zip
+      ==> Implied `brew uninstall --cask local-caffeine`
+      ==> Backing App 'Caffeine.app' up to '.*Caffeine.app'
+      ==> Removing App '.*Caffeine.app'
+      ==> Dispatching zap stanza
+      ==> Trashing files:
+      .*org\.example\.caffeine\.plist
+      ==> Removing all staged versions of Cask 'local-caffeine'
+      ==> Installing Cask local-caffeine
+      ==> Moving App 'Caffeine.app' to '.*Caffeine.app'
+      .*local-caffeine was successfully installed!
+    EOS
+
+    expect {
+      described_class.run("local-caffeine", "--zap")
+    }.to output(output).to_stdout
+  end
+
   it "allows reinstalling a Cask" do
     Cask::Cmd::Install.run("local-transmission")
 

Library/Homebrew/test/support/fixtures/cask/Casks/local-caffeine.rb

@@ -6,4 +6,6 @@ cask "local-caffeine" do
   homepage "https://brew.sh/"
 
   app "Caffeine.app"
+
+  zap trash: "#{TEST_FIXTURE_DIR}/cask/caffeine/org.example.caffeine.plist"
 end