Improvements to HOMEBREW_USE_INTERNAL_API

Author: Rylan12

Library/Homebrew/attestation.rb

@@ -98,8 +98,9 @@ def self.gh_executable
     # @api private
     sig { params(formulae: T::Array[Formula]).returns(T::Array[Formula]) }
     def self.sort_formulae_for_install(formulae)
-      if formulae.include?(Formula["gh"])
-        [Formula["gh"]] | formulae
+      gh = formulae.find { |f| f.full_name == "gh" }
+      if gh
+        [gh] | formulae
       else
         Homebrew::Attestation.gh_executable
         formulae

Library/Homebrew/cli/named_args.rb

@@ -364,8 +364,7 @@ def load_formula_or_cask(name, only: nil, method: nil, warn: false)
             begin
               case method
               when nil, :factory
-                Formulary.factory(name, *@override_spec,
-                                  warn:, force_bottle: @force_bottle, flags: @flags, prefer_stub: true)
+                Formulary.factory_stub(name, *@override_spec, warn:, force_bottle: @force_bottle, flags: @flags)
               when :resolve
                 resolve_formula(name)
               when :latest_kegs

Library/Homebrew/cli/parser.rb

@@ -733,7 +733,7 @@ def formulae(argv)
           next if arg.match?(HOMEBREW_CASK_TAP_CASK_REGEX)
 
           begin
-            Formulary.factory(arg, spec, flags: argv.select { |a| a.start_with?("--") }, prefer_stub: true)
+            Formulary.factory_stub(arg, spec, flags: argv.select { |a| a.start_with?("--") })
           rescue FormulaUnavailableError, FormulaSpecificationError
             nil
           end

Library/Homebrew/extend/kernel.rb

@@ -201,7 +201,7 @@ def ensure_executable!(name, formula_name = nil, reason: "", latest: false)
     return executable if executable.exist?
 
     require "formula"
-    Formula[formula_name].ensure_installed!(reason:, latest:).opt_bin/name
+    Formulary.factory_stub(formula_name).ensure_installed!(reason:, latest:).opt_bin/name
   end
 
   sig { params(size_in_bytes: T.any(Integer, Float)).returns(String) }

Library/Homebrew/extend/os/mac/pkgconf.rb

@@ -11,7 +11,7 @@ def macos_sdk_mismatch
       return if OS::Mac.version.prerelease? || OS::Mac.version.outdated_release?
 
       pkgconf = begin
-        ::Formula["pkgconf"]
+        ::Formulary.factory_stub("pkgconf")
       rescue FormulaUnavailableError
         nil
       end

Library/Homebrew/extend/pathname.rb

@@ -474,8 +474,8 @@ def which_install_info
     @which_install_info ||=
       if File.executable?("/usr/bin/install-info")
         "/usr/bin/install-info"
-      elsif Formula["texinfo"].any_version_installed?
-        (Formula["texinfo"].opt_bin/"install-info").to_s
+      elsif (texinfo_formula = Formulary.factory_stub("texinfo")).any_version_installed?
+        (texinfo_formula.opt_bin/"install-info").to_s
       end
   end
 end

Library/Homebrew/formulary.rb

@@ -559,7 +559,7 @@ def self.resolve(
       end
     else
       rack = to_rack(name)
-      alias_path = factory(name, force_bottle:, flags:, prefer_stub: true).alias_path
+      alias_path = factory_stub(name, force_bottle:, flags:).alias_path
       f = from_rack(rack, *spec, alias_path:, force_bottle:, flags:)
     end
 
@@ -1172,6 +1172,48 @@ def self.factory(
     formula
   end
 
+  # A shortcut for calling `factory` with `prefer_stub: true`.
+  #
+  # Note: this method returns a stubbed formula which will include only:
+  #
+  # * name
+  # * version
+  # * revision
+  # * version_scheme
+  # * bottle information (for the current OS's bottle, only)
+  # * aliases
+  # * oldnames
+  # * any other data that can be computed using only this information
+  #
+  # Only use the output for operations that do not require full formula data.
+  #
+  # @see .factory
+  # @api internal
+  sig {
+    params(
+      ref:           T.any(Pathname, String),
+      spec:          Symbol,
+      alias_path:    T.nilable(T.any(Pathname, String)),
+      from:          T.nilable(Symbol),
+      warn:          T::Boolean,
+      force_bottle:  T::Boolean,
+      flags:         T::Array[String],
+      ignore_errors: T::Boolean,
+    ).returns(Formula)
+  }
+  def self.factory_stub(
+    ref,
+    spec = :stable,
+    alias_path: nil,
+    from: nil,
+    warn: false,
+    force_bottle: false,
+    flags: [],
+    ignore_errors: false
+  )
+    factory(ref, spec, alias_path:, from:, warn:, force_bottle:, flags:, ignore_errors:, prefer_stub: true)
+  end
+
   # Return a {Formula} instance for the given rack.
   #
   # @param spec when nil, will auto resolve the formula's spec.

Library/Homebrew/style.rb

@@ -327,20 +327,20 @@ def self.github_workflow_files
 
     def self.shellcheck
       require "formula"
-      shellcheck_stub = Formulary.factory("shellcheck", prefer_stub: true)
+      shellcheck_stub = Formulary.factory_stub("shellcheck")
       shellcheck_stub.ensure_installed!(latest: true, reason: "shell style checks").opt_bin/"shellcheck"
     end
 
     def self.shfmt
       require "formula"
-      shfmt_stub = Formulary.factory("shfmt", prefer_stub: true)
+      shfmt_stub = Formulary.factory_stub("shfmt")
       shfmt_stub.ensure_installed!(latest: true, reason: "formatting shell scripts")
       HOMEBREW_LIBRARY/"Homebrew/utils/shfmt.sh"
     end
 
     def self.actionlint
       require "formula"
-      actionlint_stub = Formulary.factory("actionlint", prefer_stub: true)
+      actionlint_stub = Formulary.factory_stub("actionlint")
       actionlint_stub.ensure_installed!(latest: true, reason: "GitHub Actions checks").opt_bin/"actionlint"
     end