Module: Cask::CI::ZapCheck Private

Extended by:
SystemCommand::Mixin
Defined in:
cask/ci/zap_check.rb

Overview

This module is part of a private API. This module may only be used in the Homebrew/brew repository. Third parties should avoid using this module if possible, as it may be removed or changed without warning.

Exercises a Cask's apps and reports paths missing from its zap stanza.

Constant Summary collapse

FNMATCH_FLAGS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((File::FNM_CASEFOLD | File::FNM_EXTGLOB).freeze, Integer)
LAUNCH_TIMEOUT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

15
SETTLE_SECONDS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

10
QUIT_TIMEOUT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

10
GENERATE_ZAP_TIMEOUT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

300

Class Method Summary collapse

Methods included from SystemCommand::Mixin

command_sandbox, system_command, system_command!

Class Method Details

.covers?(existing, generated) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


186
187
188
189
190
191
192
 
# File 'cask/ci/zap_check.rb', line 186

def self.covers?(existing, generated)
  existing == generated ||
    File.fnmatch?(existing, generated, FNMATCH_FLAGS) ||
    # Generated paths may themselves contain wildcards (e.g. collapsed
    # UUIDs), which an existing literal entry can never fnmatch.
    File.fnmatch?(generated, existing, FNMATCH_FLAGS)
end

.descendant?(path, of:) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


195
196
197
 
# File 'cask/ci/zap_check.rb', line 195

def self.descendant?(path, of:)
  path.downcase.start_with?("#{of.downcase}/")
end

.exercise(apps) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'cask/ci/zap_check.rb', line 81

def self.exercise(apps)
  return if apps.empty?

  apps.each do |app|
    # Gatekeeper blocks `open` on quarantined apps and the quarantine
    # attribute has already been verified during `brew install`.
    system_command "/usr/bin/xattr", args: ["-dr", "com.apple.quarantine", app.to_s], print_stderr: false
    launch app

    puts "Warning: #{app} was not running after #{LAUNCH_TIMEOUT} seconds." unless wait_until(LAUNCH_TIMEOUT) do
      running?(app)
    end
  end

  sleep SETTLE_SECONDS

  quit apps
end

.generate_zap(cask_path) ⇒ SystemCommand::Result?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



69
70
71
72
73
74
75
76
77
78
 
# File 'cask/ci/zap_check.rb', line 69

def self.generate_zap(cask_path)
  args = ["generate-zap"]
  args << "--tap-source" if cask_path.end_with?(".rb")
  system_command ENV.fetch("HOMEBREW_BREW_FILE"),
                 args:         [*args, cask_path],
                 print_stderr: false,
                 timeout:      GENERATE_ZAP_TIMEOUT
rescue Timeout::Error
  nil
end

.launch(app) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



101
102
103
104
105
106
107
108
109
110
 
# File 'cask/ci/zap_check.rb', line 101

def self.launch(app)
  result = system_command "/usr/bin/open", args: ["-g", app.to_s], print_stderr: false,
                                           timeout: LAUNCH_TIMEOUT
  return if result.success?

  puts "Warning: Failed to open #{app} (exit status: #{result.exit_status}):"
  puts result.merged_output
rescue Timeout::Error
  puts "Warning: Timed out opening #{app} after #{LAUNCH_TIMEOUT} seconds."
end

.process_pattern(app) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



154
155
156
 
# File 'cask/ci/zap_check.rb', line 154

def self.process_pattern(app)
  "^#{Regexp.escape("#{app}/")}"
end

.quit(apps) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Ask the app to quit the same way uninstall quit: does, which also prompts cfprefsd to write the app's preferences to disk, where brew generate-zap can find them. An app that ignores the request is left running: signalling it instead denies it the chance to undo any system-wide changes it made.

Parameters:



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'cask/ci/zap_check.rb', line 117

def self.quit(apps)
  apps.each do |app|
    script = <<~JAVASCRIPT
      'use strict';

      ObjC.import('stdlib')

      function run(argv) {
        var app = Application(argv[0])

        try {
          app.quit()
        } catch (err) {
          if (app.running()) {
            $.exit(1)
          }
        }

        $.exit(0)
      }
    JAVASCRIPT
    system_command "osascript", args: ["-l", "JavaScript", "-e", script, app.to_s], print_stderr: false

    next if wait_until(QUIT_TIMEOUT) { !running?(app) }

    puts "Warning: #{app} did not quit when asked; leaving it running."
  end

  sleep 3
end

.reject_covered(cask, generated_paths) ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'cask/ci/zap_check.rb', line 170

def self.reject_covered(cask, generated_paths)
  zap_directives = cask.artifacts.grep(::Cask::Artifact::Zap).map(&:directives)
  deletable_paths = zap_directives.flat_map { |directives| directives.values_at(:trash, :delete) }
                                  .flatten.compact.map(&:to_s)
  # `rmdir` only removes empty directories, so it covers a generated path
  # itself but not anything beneath it.
  rmdir_paths = zap_directives.flat_map { |directives| directives[:rmdir] }
                              .flatten.compact.map(&:to_s)

  generated_paths.reject do |generated|
    deletable_paths.any? { |existing| covers?(existing, generated) || descendant?(generated, of: existing) } ||
      rmdir_paths.any? { |existing| covers?(existing, generated) }
  end
end

.report(cask_path, intro, body) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'cask/ci/zap_check.rb', line 200

def self.report(cask_path, intro, body)
  puts GitHub::Actions::Annotation.new(:warning, "#{intro}\n#{body}",
                                       file: cask_path, title: "Possible missing zap paths")

  summary_path = ENV.fetch("GITHUB_STEP_SUMMARY", nil)
  return unless summary_path

  File.open(summary_path, "a") do |file|
    file.puts <<~MARKDOWN
      ## Possible missing zap paths

      #{intro}

      ```text
      #{body}
      ```
    MARKDOWN
  end
end

.run(cask_path) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Parameters:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'cask/ci/zap_check.rb', line 24

def self.run(cask_path)
  $stdout.sync = true

  cask = if cask_path.end_with?(".rb")
    ::Cask::CaskLoader.from_tap_path(cask_path)
  else
    ::Cask::CaskLoader.load(cask_path)
  end
  apps = cask.artifacts.grep(::Cask::Artifact::App).map(&:target).select(&:directory?)
  exercise(apps)

  result = generate_zap(cask_path)
  if result.nil?
    report cask_path, "Unable to check `#{cask.token}`:",
           "`brew generate-zap` timed out after #{GENERATE_ZAP_TIMEOUT} seconds."
    return
  end

  unless result.success?
    report cask_path, "Unable to check `#{cask.token}` with `brew generate-zap`:",
           Tty.strip_ansi(result.stderr.presence || result.stdout)
    return
  end

  stanza = Tty.strip_ansi(result.stdout)[/^zap .*/m]
  generated_paths = stanza&.scan(/"([^"]+)"/)&.flatten
  if generated_paths.blank?
    puts "brew generate-zap found no leftover files for #{cask.token}."
    return
  end

  puts "Stanza generated by brew generate-zap:", stanza, ""

  missing_paths = reject_covered(cask, generated_paths)
  if missing_paths.empty?
    puts "All #{generated_paths.count} generated paths are covered by the existing zap stanza."
    return
  end

  report cask_path,
         "`brew generate-zap` found paths not covered by the current `zap` stanza of `#{cask.token}`:",
         missing_paths.join("\n")
end

.running?(app) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


149
150
151
 
# File 'cask/ci/zap_check.rb', line 149

def self.running?(app)
  system_command("/usr/bin/pgrep", args: ["-f", process_pattern(app)], print_stderr: false).success?
end

.wait_until(timeout, &block) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • timeout (Integer)
  • block (T.proc.returns(T::Boolean))

Returns:

  • (Boolean) 


159
160
161
162
163
164
165
166
167
 
# File 'cask/ci/zap_check.rb', line 159

def self.wait_until(timeout, &block)
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
  loop do
    return true if yield
    return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline

    sleep 0.5
  end
end