GithubLatest: Update documentation

Library/Homebrew/livecheck/strategy/github_latest.rb

@@ -5,30 +5,25 @@ module Homebrew
   module Livecheck
     module Strategy
       # The {GithubLatest} strategy identifies versions of software at
-      # github.com by checking a repository's "latest" release page.
+      # github.com by checking a repository's "latest" release using the
+      # GitHub API.
       #
       # GitHub URLs take a few different formats:
       #
       # * `https://github.com/example/example/releases/download/1.2.3/example-1.2.3.tar.gz`
       # * `https://github.com/example/example/archive/v1.2.3.tar.gz`
       # * `https://github.com/downloads/example/example/example-1.2.3.tar.gz`
       #
-      # A repository's `/releases/latest` URL normally redirects to a release
-      # tag (e.g., `/releases/tag/1.2.3`). When there isn't a "latest" release,
-      # it will redirect to the `/releases` page.
+      # {GithubLatest} should only be used when the upstream repository has a
+      # "latest" release for a suitable version and the strategy is necessary
+      # or appropriate (e.g. {Git} returns an unreleased version or the
+      # `stable` URL is a release asset). The strategy can only be applied by
+      # using `strategy :github_latest` in a `livecheck` block.
       #
-      # This strategy should only be used when we know the upstream repository
-      # has a "latest" release and the tagged release is appropriate to use
-      # (e.g., "latest" isn't wrongly pointing to an unstable version, not
-      # picking up the actual latest version, etc.). The strategy can only be
-      # applied by using `strategy :github_latest` in a `livecheck` block.
-      #
-      # The default regex identifies versions like `1.2.3`/`v1.2.3` in `href`
-      # attributes containing the tag URL (e.g.,
-      # `/example/example/releases/tag/v1.2.3`). This is a common tag format
-      # but a modified regex can be provided in a `livecheck` block to override
-      # the default if a repository uses a different format (e.g.,
-      # `example-1.2.3`, `1.2.3d`, `1.2.3-4`, etc.).
+      # The default regex identifies versions like `1.2.3`/`v1.2.3` in the
+      # release's tag name. This is a common tag format but a modified regex
+      # can be provided in a `livecheck` block to override the default if a
+      # repository uses a different format (e.g. `1.2.3d`, `1.2.3-4`, etc.).
       #
       # @api public
       class GithubLatest
@@ -50,8 +45,9 @@ class GithubLatest
         # isn't provided.
         DEFAULT_REGEX = /v?(\d+(?:\.\d+)+)/i.freeze
 
-        # Keys in the JSON that could contain the version.
-        VERSION_KEYS = ["name", "tag_name"].freeze
+        # Keys in the release JSON that could contain the version.
+        # Tag name first since that is closer to other livechecks.
+        VERSION_KEYS = ["tag_name", "name"].freeze
 
         # Whether the strategy can be applied to the provided URL.
         #
@@ -83,22 +79,23 @@ def self.generate_input_values(url)
           values
         end
 
-        # Uses the regex to match release information in content or, if a block is
-        # provided, passes the page content to the block to handle matching.
-        # With either approach, an array of unique matches is returned.
+        # Uses a regex to match the version from release JSON or, if a block is
+        # provided, passes the JSON to the block to handle matching. With
+        # either approach, an array of unique matches is returned.
         #
-        # @param content [Array] list of releases
+        # @param content [Array, Hash] list of releases or a single release
         # @param regex [Regexp] a regex used for matching versions in the content
         # @param block [Proc, nil] a block to match the content
         # @return [Array]
         sig {
           params(
-            content: T::Array[T::Hash[String, T.untyped]],
+            content: T.any(T::Array[T::Hash[String, T.untyped]], T::Hash[String, T.untyped]),
             regex:   Regexp,
             block:   T.nilable(Proc),
           ).returns(T::Array[String])
         }
         def self.versions_from_content(content, regex, &block)
+          content = [content] unless content.kind_of?(Array)
           if block.present?
             block_return_value = if regex.present?
               yield(content, regex)
@@ -113,14 +110,17 @@ def self.versions_from_content(content, regex, &block)
 
             value = T.let(nil, T.untyped)
             VERSION_KEYS.find do |key|
-              value = release[key]&.match(regex)&.to_s
+              match = release[key]&.match(regex)
+              next if match.blank?
+
+              value = match[1]&.to_s
             end
             value
           end.compact.uniq
         end
 
-        # Generates a URL and regex (if one isn't provided) and passes them
-        # to {PageMatch.find_versions} to identify versions in the content.
+        # Generates the GitHub API URL for the repository's "latest" release
+        # and identifies the version from the JSON response.
         #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content
@@ -142,7 +142,7 @@ def self.find_versions(url:, regex: DEFAULT_REGEX, **_unused, &block)
           match_data[:url] = generated[:url]
 
           release = GitHub.get_latest_release(generated[:username], generated[:repository])
-          versions_from_content([release], regex, &block).each do |match_text|
+          versions_from_content(release, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end