Improve extend/* Sorbet typing

Author: MikeMcQuaid

Library/Homebrew/extend/kernel.rb

@@ -2,7 +2,8 @@
 # frozen_string_literal: true
 
 # Contains shorthand Homebrew utility methods like `ohai`, `opoo`, `odisabled`.
-# TODO: move these out of `Kernel`.
+# TODO: move these out of `Kernel` into `Homebrew::GlobalMethods` and add
+# necessary Sorbet and global Kernel inclusions.
 
 module Kernel
   sig { params(env: T.nilable(String)).returns(T::Boolean) }
@@ -13,23 +14,25 @@ def superenv?(env)
   end
   private :superenv?
 
+  sig { params(path: T.nilable(T.any(String, Pathname))).returns(T::Boolean) }
   def require?(path)
     return false if path.nil?
 
     if defined?(Warnings)
       # Work around require warning when done repeatedly:
       # https://bugs.ruby-lang.org/issues/21091
       Warnings.ignore(/already initialized constant/, /previous definition of/) do
-        require path
+        require path.to_s
       end
     else
-      require path
+      require path.to_s
     end
     true
   rescue LoadError
     false
   end
 
+  sig { params(title: String).returns(String) }
   def ohai_title(title)
     verbose = if respond_to?(:verbose?)
       T.unsafe(self).verbose?
@@ -42,7 +45,7 @@ def ohai_title(title)
   end
 
   def ohai(title, *sput)
-    puts ohai_title(title)
+    puts ohai_title(title.to_s)
     puts sput
   end
 
@@ -55,10 +58,11 @@ def odebug(title, *sput, always_display: false)
 
     return if !debug && !always_display
 
-    $stderr.puts Formatter.headline(title, color: :magenta)
+    $stderr.puts Formatter.headline(title.to_s, color: :magenta)
     $stderr.puts sput unless sput.empty?
   end
 
+  sig { params(title: String, truncate: T.any(Symbol, T::Boolean)).returns(String) }
   def oh1_title(title, truncate: :auto)
     verbose = if respond_to?(:verbose?)
       T.unsafe(self).verbose?
@@ -70,6 +74,7 @@ def oh1_title(title, truncate: :auto)
     Formatter.headline(title, color: :green)
   end
 
+  sig { params(title: String, truncate: T.any(Symbol, T::Boolean)).void }
   def oh1(title, truncate: :auto)
     puts oh1_title(title, truncate:)
   end
@@ -134,6 +139,10 @@ def odie(error)
   end
 
   # Output a deprecation warning/error message.
+  sig {
+    params(method: String, replacement: T.nilable(T.any(String, Symbol)), disable: T::Boolean,
+           disable_on: T.nilable(Time), disable_for_developers: T::Boolean, caller: T::Array[String]).void
+  }
   def odeprecated(method, replacement = nil,
                   disable:                false,
                   disable_on:             nil,
@@ -213,12 +222,20 @@ def odeprecated(method, replacement = nil,
     end
   end
 
-  def odisabled(method, replacement = nil, **options)
-    options = { disable: true, caller: }.merge(options)
+  sig {
+    params(method: String, replacement: T.nilable(T.any(String, Symbol)), disable: T::Boolean,
+           disable_on: T.nilable(Time), disable_for_developers: T::Boolean, caller: T::Array[String]).void
+  }
+  def odisabled(method, replacement = nil,
+                disable:                false,
+                disable_on:             nil,
+                disable_for_developers: true,
+                caller:                 send(:caller))
     # This odeprecated should stick around indefinitely.
-    odeprecated(method, replacement, **options)
+    odeprecated(method, replacement, disable:, disable_on:, disable_for_developers:, caller:)
   end
 
+  sig { params(formula: T.any(String, Formula)).returns(String) }
   def pretty_installed(formula)
     if !$stdout.tty?
       formula.to_s
@@ -229,6 +246,7 @@ def pretty_installed(formula)
     end
   end
 
+  sig { params(formula: T.any(String, Formula)).returns(String) }
   def pretty_outdated(formula)
     if !$stdout.tty?
       formula.to_s
@@ -239,6 +257,7 @@ def pretty_outdated(formula)
     end
   end
 
+  sig { params(formula: T.any(String, Formula)).returns(String) }
   def pretty_uninstalled(formula)
     if !$stdout.tty?
       formula.to_s
@@ -249,6 +268,7 @@ def pretty_uninstalled(formula)
     end
   end
 
+  sig { params(seconds: T.nilable(T.any(Integer, Float))).returns(String) }
   def pretty_duration(seconds)
     seconds = seconds.to_i
     res = +""
@@ -266,9 +286,10 @@ def pretty_duration(seconds)
     res.freeze
   end
 
+  sig { params(formula: T.nilable(Formula)).void }
   def interactive_shell(formula = nil)
     unless formula.nil?
-      ENV["HOMEBREW_DEBUG_PREFIX"] = formula.prefix
+      ENV["HOMEBREW_DEBUG_PREFIX"] = formula.prefix.to_s
       ENV["HOMEBREW_DEBUG_INSTALL"] = formula.full_name
     end
 
@@ -295,6 +316,7 @@ def with_custom_locale(locale, &block)
 
   # Kernel.system but with exceptions.
   def safe_system(cmd, *args, **options)
+    # TODO: migrate to utils.rb Homebrew.safe_system
     require "utils"
 
     return if Homebrew.system(cmd, *args, **options)
@@ -306,6 +328,7 @@ def safe_system(cmd, *args, **options)
   #
   # @api internal
   def quiet_system(cmd, *args)
+    # TODO: migrate to utils.rb Homebrew.quiet_system
     require "utils"
 
     Homebrew._system(cmd, *args) do
@@ -367,11 +390,13 @@ def which_editor(silent: false)
     editor
   end
 
-  def exec_editor(*args)
-    puts "Editing #{args.join "\n"}"
-    with_homebrew_path { safe_system(*which_editor.shellsplit, *args) }
+  sig { params(filename: T.any(String, Pathname)).void }
+  def exec_editor(filename)
+    puts "Editing #{filename}"
+    with_homebrew_path { safe_system(*which_editor.shellsplit, filename) }
   end
 
+  sig { params(args: T.any(String, Pathname)).void }
   def exec_browser(*args)
     browser = Homebrew::EnvConfig.browser
     browser ||= OS::PATH_OPEN if defined?(OS::PATH_OPEN)
@@ -384,7 +409,7 @@ def exec_browser(*args)
     end
   end
 
-  IGNORE_INTERRUPTS_MUTEX = Thread::Mutex.new.freeze
+  IGNORE_INTERRUPTS_MUTEX = T.let(Thread::Mutex.new.freeze, Thread::Mutex)
 
   def ignore_interrupts
     IGNORE_INTERRUPTS_MUTEX.synchronize do
@@ -417,6 +442,10 @@ def redirect_stdout(file)
 
   # Ensure the given formula is installed
   # This is useful for installing a utility formula (e.g. `shellcheck` for `brew style`)
+  sig {
+    params(formula_or_name: T.any(String, Formula), reason: String, latest: T::Boolean, output_to_stderr: T::Boolean,
+           quiet: T::Boolean).returns(Formula)
+  }
   def ensure_formula_installed!(formula_or_name, reason: "", latest: false,
                                 output_to_stderr: true, quiet: false)
     if output_to_stderr || quiet
@@ -456,6 +485,7 @@ def ensure_formula_installed!(formula_or_name, reason: "", latest: false,
   end
 
   # Ensure the given executable is exist otherwise install the brewed version
+  sig { params(name: String, formula_name: T.nilable(String), reason: String, latest: T::Boolean).returns(T.nilable(Pathname)) }
   def ensure_executable!(name, formula_name = nil, reason: "", latest: false)
     formula_name ||= name
 
@@ -472,10 +502,12 @@ def ensure_executable!(name, formula_name = nil, reason: "", latest: false)
     ensure_formula_installed!(formula_name, reason:, latest:).opt_bin/name
   end
 
+  sig { returns(T::Array[Pathname]) }
   def paths
-    @paths ||= ORIGINAL_PATHS.uniq.map(&:to_s)
+    @paths ||= T.let(ORIGINAL_PATHS.uniq.map(&:to_s), T.nilable(T::Array[Pathname]))
   end
 
+  sig { params(size_in_bytes: T.any(Integer, Float)).returns(String) }
   def disk_usage_readable(size_in_bytes)
     if size_in_bytes.abs >= 1_073_741_824
       size = size_in_bytes.to_f / 1_073_741_824
@@ -509,6 +541,7 @@ def number_readable(number)
   # preserving character encoding validity. The returned string will
   # be not much longer than the specified max_bytes, though the exact
   # shortfall or overrun may vary.
+  sig { params(str: String, max_bytes: Integer, options: T::Hash[Symbol, T.untyped]).returns(String) }
   def truncate_text_to_approximate_size(str, max_bytes, options = {})
     front_weight = options.fetch(:front_weight, 0.5)
     raise "opts[:front_weight] must be between 0.0 and 1.0" if front_weight < 0.0 || front_weight > 1.0
@@ -530,7 +563,7 @@ def truncate_text_to_approximate_size(str, max_bytes, options = {})
       front = bytes[0..(n_front_bytes - 1)]
       back = bytes[-n_back_bytes..]
     end
-    out = front + glue_bytes + back
+    out = T.must(front) + glue_bytes + T.must(back)
     out.force_encoding("UTF-8")
     out.encode!("UTF-16", invalid: :replace)
     out.encode!("UTF-8")
@@ -568,6 +601,7 @@ def with_env(hash)
     end
   end
 
+  sig { returns(T.proc.params(a: String, b: String).returns(Integer)) }
   def tap_and_name_comparison
     proc do |a, b|
       if a.include?("/") && b.exclude?("/")
@@ -580,6 +614,7 @@ def tap_and_name_comparison
     end
   end
 
+  sig { params(input: String, secrets: T::Array[String]).returns(String) }
   def redact_secrets(input, secrets)
     secrets.compact
            .reduce(input) { |str, secret| str.gsub secret, "******" }