Replace brew which-update

- Keep `brew which-update` as the CI-facing command because core CI now
  updates command-not-found entries from bottle metadata.
- Drop the old bulk scan, stats and commit paths because the database is
  no longer refreshed by a scheduled repository commit.
- Limit `executables_db.rb` updates to bottle JSON metadata and explicit
  formula removals.
- Regenerate command docs, completions and Sorbet RBI for the narrower
  command interface.

Author: MikeMcQuaid

.github/workflows/command-not-found-db-update.yml

@@ -6,6 +6,7 @@
 
 require "abstract_command"
 require "executables_db"
+require "utils/github"
 
 module Homebrew
   module DevCmd
@@ -14,143 +15,98 @@ class WhichUpdate < AbstractCommand
         description <<~EOS
           Database update for `brew which-formula`.
         EOS
-        switch "--stats",
-               description: "Print statistics about the database contents (number of commands and formulae, " \
-                            "list of missing formulae)."
-        switch "--commit",
-               description: "Commit the changes using `git`."
-        switch "--update-existing",
-               description: "Update database entries with outdated formula versions."
-        switch "--install-missing",
-               description: "Install and update formulae that are missing from the database and don't have bottles."
-        switch "--eval-all",
-               description: "Evaluate all installed taps, rather than just the core tap."
-        flag   "--max-downloads=",
-               description: "Specify a maximum number of formulae to download and update."
+        flag   "--bottle-json-dir=",
+               description: "Use generated bottle JSON files in the given directory to update formula entries."
+        flag   "--removed-formulae-file=",
+               description: "Remove database entries for formulae listed in the given file."
+        flag   "--pull-request=",
+               description: "Update entries for formula changes in the given pull request number."
+        flag   "--repository=",
+               depends_on:  "--pull-request",
+               description: "GitHub repository for `--pull-request` (default: `$GITHUB_REPOSITORY`)."
         flag   "--summary-file=",
                description: "Output a summary of the changes to a file."
-        conflicts "--stats", "--commit"
-        conflicts "--stats", "--install-missing"
-        conflicts "--stats", "--update-existing"
-        conflicts "--stats", "--max-downloads"
         named_args :database, number: 1
       end
 
       sig { override.void }
       def run
-        if args.stats?
-          stats source: args.named.fetch(0)
-        else
-          update_and_save! source:          args.named.fetch(0),
-                           commit:          args.commit?,
-                           update_existing: args.update_existing?,
-                           install_missing: args.install_missing?,
-                           max_downloads:   args.max_downloads&.to_i,
-                           eval_all:        args.eval_all?,
-                           summary_file:    args.summary_file
+        updated = update_and_save! source:                args.named.fetch(0),
+                                   bottle_json_dir:       args.bottle_json_dir,
+                                   removed_formulae_file: args.removed_formulae_file,
+                                   pull_request:          args.pull_request,
+                                   repository:            args.repository,
+                                   summary_file:          args.summary_file
+
+        if (github_output = ENV["GITHUB_OUTPUT"].presence)
+          File.open(github_output, "a") { |file| file.puts "updated=#{updated}" }
         end
       end
 
-      sig { params(source: String).void }
-      def stats(source:)
-        opoo "The DB file doesn't exist." unless File.exist? source
-        db = ExecutablesDB.new source
-
-        formulae = db.formula_names
-        core = Formula.core_names
-
-        cmds_count = db.exes.values.reduce(0) { |s, exs| s + exs.binaries.size }
-
-        core_percentage = ((formulae & core).size * 1000 / core.size.to_f).round / 10.0
-
-        missing = (core - formulae).reject { |f| Formula[f].disabled? }
-        puts <<~EOS
-          #{formulae.size} formulae
-          #{cmds_count} commands
-          #{core_percentage}%  (missing: #{missing * " "})
-        EOS
-
-        unknown = formulae - Formula.full_names
-        puts "\nUnknown formulae: #{unknown * ", "}." if unknown.any?
-        nil
-      end
-
       sig {
         params(
-          source:          String,
-          commit:          T::Boolean,
-          update_existing: T::Boolean,
-          install_missing: T::Boolean,
-          max_downloads:   T.nilable(Integer),
-          eval_all:        T::Boolean,
-          summary_file:    T.nilable(String),
-        ).void
+          source:                String,
+          bottle_json_dir:       T.nilable(String),
+          removed_formulae_file: T.nilable(String),
+          pull_request:          T.nilable(String),
+          repository:            T.nilable(String),
+          summary_file:          T.nilable(String),
+        ).returns(T::Boolean)
       }
-      def update_and_save!(source:, commit: false, update_existing: false, install_missing: false,
-                           max_downloads: nil, eval_all: false, summary_file: nil)
+      def update_and_save!(source:, bottle_json_dir: nil, removed_formulae_file: nil, pull_request: nil,
+                           repository: nil, summary_file: nil)
+        source_path = Pathname(source)
+        original_database = source_path.exist? ? source_path.read : nil
         db = ExecutablesDB.new source
-        db.update!(update_existing:, install_missing:,
-                   max_downloads:, eval_all:)
-        db.save!
 
-        if summary_file
-          msg = summary_file_message(db.changes)
-          File.open(summary_file, "a") do |file|
-            file.puts(msg)
-          end
+        removed_formulae = if removed_formulae_file.blank? || !File.file?(removed_formulae_file)
+          []
+        else
+          File.readlines(removed_formulae_file, chomp: true).filter_map { |line| line.strip.presence }
         end
 
-        return if !commit || !db.changed?
-
-        msg = git_commit_message(db.changes)
-        safe_system "git", "-C", db.root.to_s, "commit", "-m", msg, source
-      end
-
-      sig { params(els: T::Array[String], verb: String).returns(String) }
-      def english_list(els, verb)
-        msg = +""
-        msg << els.slice(0, 3)&.join(", ")
-        msg << " and #{els.length - 3} more" if msg.length < 40 && els.length > 3
-        "#{verb.capitalize} #{msg}"
-      end
+        if pull_request
+          repository = repository.presence || ENV["GITHUB_REPOSITORY"].presence
+          if repository.blank?
+            raise UsageError,
+                  "`--repository` or `$GITHUB_REPOSITORY` is required with `--pull-request`."
+          end
 
-      sig { params(changes: ExecutablesDB::Changes).returns(String) }
-      def git_commit_message(changes)
-        msg = []
-        ExecutablesDB::Changes::TYPES.each do |action|
-          names = changes.send(action)
-          next if names.empty?
+          owner, repo = repository.split("/", 2)
+          if owner.blank? || repo.blank? || repo.include?("/")
+            raise UsageError, "`--repository` must be in the form `owner/repo`."
+          end
 
-          action = "bump version for" if action == :version_bump
-          msg << english_list(names.to_a.sort, action.to_s)
-          break
+          GitHub::API.paginate_rest(GitHub.url_to("repos", owner, repo, "pulls", pull_request, "files")) do |files|
+            T.cast(files, T::Array[T::Hash[String, T.untyped]]).each do |file|
+              filename = file["filename"].to_s
+              next if !filename.start_with?("Formula/") || !filename.end_with?(".rb")
+
+              case file["status"].to_s
+              when "removed"
+                removed_formulae << File.basename(filename, ".rb")
+              when "renamed"
+                removed_formulae << File.basename(file["previous_filename"].to_s, ".rb")
+              end
+            end
+          end
         end
 
-        msg.join
-      end
+        db.update!(bottle_json_dir:, removed_formulae:)
+        db.save!
+        updated = original_database != source_path.read
 
-      sig { params(changes: ExecutablesDB::Changes).returns(String) }
-      def summary_file_message(changes)
-        msg = []
-        ExecutablesDB::Changes::TYPES.each do |action|
-          names = changes.send(action)
-          next if names.empty?
+        if summary_file
+          File.open(summary_file, "a") do |file|
+            file.puts <<~EOS
+              ## Database Update Summary
 
-          action_heading = action.to_s.split("_").map(&:capitalize).join(" ")
-          msg << "### #{action_heading}"
-          msg << ""
-          names.to_a.sort.each do |name|
-            msg << "- [`#{name}`](https://formulae.brew.sh/formula/#{name})"
+              #{updated ? "Updated command-not-found database." : "No changes"}
+            EOS
           end
         end
 
-        msg << "No changes" if msg.empty?
-
-        <<~MESSAGE
-          ## Database Update Summary
-
-          #{msg.join("\n")}
-        MESSAGE
+        updated
       end
     end
   end