shields-badge 1.0.0

data/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported | Enterprise Support                    |
+|----------|-----------|---------------------------------------|
+| 1.latest | ✅         | [Tidelift Subscription][tidelift-ref] |
+
+### EOL Policy
+
+Non-commercial support for the oldest version of Ruby (which itself is going EOL) may be dropped each year in April.
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Shields Badge for Enterprise
+
+Available as part of the Tidelift Subscription.
+
+The maintainers of shields-badge and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. [Learn more.][tidelift-ref]
+
+[tidelift-ref]: https://tidelift.com/subscription/pkg/rubygems-shields-badge?utm_source=rubygems-shields-badge&utm_medium=referral&utm_campaign=enterprise&utm_term=repo

data/lib/shields/anchor_href_template.rb

@@ -0,0 +1,11 @@
+module Shields
+  class AnchorHrefTemplate
+    def initialize(path)
+      @path = path
+    end
+
+    def call(**args)
+      @path % args
+    end
+  end
+end

data/lib/shields/api_template.rb

@@ -0,0 +1,11 @@
+module Shields
+  class ApiTemplate
+    def initialize(path)
+      @path = path
+    end
+
+    def call(**args)
+      @path % args
+    end
+  end
+end

data/lib/shields/badge/activity/github_commits_since_latest_release.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module Activity
+      # Shield for the number of GitHub commits since the last release
+      # See: https://shields.io/badges/git-hub-commits-since-latest-release
+      class GithubCommitsSinceLatestRelease < Base
+        class PathDto < ::Castkit::DataObject
+          enable_plugins :path_plugin
+          enable_plugins :github_repo_plugin
+        end
+
+        class QueryDto < ::Castkit::DataObject
+          OPTIONS = {
+            sort: %w[date semver],
+            include_prereleases: %w[true false],
+          }
+          FILTER_MATCHER = /[*!]/
+
+          enable_plugins :query_plugin
+
+          optional do
+            string :include_prereleases, ignore_nil: true, validator: ->(v, _options) {
+              raise Errors::ValidationError, "invalid option for include_prereleases, must be one of #{OPTIONS[:include_prereleases]}" if v && !OPTIONS[:include_prereleases].include?(v)
+              true
+            }
+            string :sort, ignore_nil: true, validator: ->(v, _options) {
+              raise Errors::ValidationError, "invalid option for sort, must be one of #{OPTIONS[:sort]}" if v && !OPTIONS[:sort].include?(v)
+              true
+            }
+            string :filter, ignore_nil: true, validator: ->(v, _options) {
+              raise Errors::ValidationError, "invalid option for filter, must use * or ! but was #{v}" if v && !v[FILTER_MATCHER]
+              true
+            }
+          end
+        end
+
+        class << self
+          # Formatted string specification template
+          # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+          def api_template = "/github/commits-since/%{user}/%{repo}/latest"
+
+          def anchor_href_template = "https://github.com/%{user}/%{repo}/releases"
+
+          def label_text_template = "%{user}/%{repo} commits since latest release"
+        end
+      end
+    end
+  end
+end

data/lib/shields/badge/base.rb

@@ -0,0 +1,90 @@
+require "uri"
+
+module Shields
+  module Badge
+    class Base
+      HTTP_METHOD = :get
+      BASE_URL = {
+        "svg" => "https://img.shields.io",
+        "png" => "https://raster.shields.io",
+      }
+
+      class << self
+        def label_text
+          raise Errors::NotImplemented, "Subclasses must implement #label_text"
+        end
+
+        def img_src_url
+          raise Errors::NotImplemented, "Subclasses must implement #img_src_url"
+        end
+
+        def anchor_href_url
+          raise Errors::NotImplemented, "Subclasses must implement #anchor_href_url"
+        end
+      end
+
+      attr_accessor :path_parameters,
+        :query_parameters,
+        :image_type,
+        :anchor_href,
+        :anchor_params,
+        :label
+
+      def initialize(path_parameters: {}, query_parameters: {}, image_type: "svg", **options)
+        if path_parameters.nil? || path_parameters.empty?
+          path_parameters = extract_top_level_options(options, self.class::PathDto)
+        end
+        if query_parameters.nil? || query_parameters.empty?
+          query_parameters = extract_top_level_options(options, self.class::QueryDto)
+        end
+        self.path_parameters = self.class::PathDto.new(**path_parameters)
+        self.query_parameters = self.class::QueryDto.new(**query_parameters)
+        self.image_type = image_type
+        self.anchor_href = options.fetch(:anchor_href, nil)
+        self.anchor_params = options.fetch(:anchor_params, {})
+        self.label = options.fetch(:label, nil)
+      end
+
+      def format(formatter)
+        args = formatter.signature.each_with_object({}) { |key, memo| memo[key] = send(key) }
+        formatter.call(
+          **args,
+        )
+      end
+
+      protected
+
+      def extract_top_level_options(options, dto_klass)
+        path_dto_klass = dto_klass
+        main_args = path_dto_klass.attributes.keys
+        args_for_dto = path_dto_klass.attributes.values.each_with_object(main_args) { |at, arr| arr.concat(at.options[:aliases].map(&:to_sym)) }
+        options.select { |k, _v| args_for_dto.include?(k) }
+      end
+
+      # Formatted string specification template
+      # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+      def label_text
+        label || LabelTextTemplate.new(self.class.label_text_template)
+          .call(**path_parameters.to_h)
+      end
+
+      def img_src_url
+        URI("#{base_url}#{ApiTemplate.new(self.class.api_template)
+                                      .call(**path_parameters.to_h)}")
+          .tap { |uri| uri.query = URI.encode_www_form(query_parameters.to_h) }
+          .to_s
+      end
+
+      def anchor_href_url
+        anchor_href || AnchorHrefTemplate.new(self.class.anchor_href_template)
+          .call(**path_parameters.to_h.merge(anchor_params))
+      end
+
+      def base_url
+        raise Errors::Error, "Unknown image type: #{image_type} must be one of #{BASE_URL.keys}" unless BASE_URL.key?(image_type)
+
+        BASE_URL[image_type]
+      end
+    end
+  end
+end

data/lib/shields/badge/build/github_branch_check_runs.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module Build
+      # Shield for GitHub Actions CI status
+      # See: https://shields.io/badges/git-hub-branch-check-runs
+      class GithubBranchCheckRuns < Base
+        class PathDto < ::Castkit::DataObject
+          enable_plugins :path_plugin
+          enable_plugins :github_repo_plugin
+          enable_plugins :git_branch_plugin
+        end
+
+        class QueryDto < ::Castkit::DataObject
+          enable_plugins :query_plugin
+
+          optional do
+            string :name_filter, ignore_nil: true, aliases: %w(nameFilter)
+          end
+
+          # Calls up to QueryPlugin#camel_case_keys
+          def camel_case_keys
+            super + [:name_filter]
+          end
+        end
+
+        class << self
+          # Formatted string specification template
+          # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+          def api_template = "/github/check-runs/%{user}/%{repo}/%{branch}"
+
+          def anchor_href_template = "https://github.com/%{user}/%{repo}/actions"
+
+          def label_text_template = "%{user}/%{repo} check runs (branch: %{branch})"
+        end
+      end
+    end
+  end
+end

data/lib/shields/badge/code_coverage/coveralls.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module CodeCoverage
+      # Shield for Coveralls test coverage
+      # See: https://shields.io/badges/coveralls
+      class Coveralls < Base
+        class PathDto < ::Castkit::DataObject
+          VCS_TYPES = %w[github bitbucket gitlab].freeze
+          enable_plugins :path_plugin
+          enable_plugins :github_repo_plugin
+
+          required do
+            string :vcs_type, ignore_nil: true, aliases: %w(vcsType), validator: ->(v, _options) {
+              raise Errors::ValidationError, "invalid option for vcs_type, must be one of #{VCS_TYPES}" if v && !VCS_TYPES.include?(v)
+              true
+            }
+          end
+        end
+
+        class QueryDto < ::Castkit::DataObject
+          enable_plugins :query_plugin
+
+          optional do
+            string :branch, ignore_nil: true
+          end
+        end
+
+        class << self
+          # Formatted string specification template
+          # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+          def api_template = "/coverallsCoverage/%{vcs_type}/%{user}/%{repo}"
+
+          def anchor_href_template = "https://github.com/%{user}/%{repo}/actions"
+
+          def label_text_template = "%{user}/%{repo} test coverage"
+        end
+      end
+    end
+  end
+end

data/lib/shields/badge/downloads/gem_download_rank.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module Downloads
+      # Shield for RubyGem total downloads
+      # # See: https://shields.io/badges/gem-download-rank
+      class GemDownloadRank < Base
+        class PathDto < ::Castkit::DataObject
+          PERIODS = %w[rt rd].freeze
+          enable_plugins :path_plugin
+          required do
+            string :gem, ignore_nil: true
+            string :period, ignore_nil: true, validator: ->(v, _options) {
+              raise Errors::ValidationError, "invalid option for period, must be one of #{PERIODS}" if v && !PERIODS.include?(v)
+              true
+            }
+          end
+        end
+
+        class QueryDto < ::Castkit::DataObject
+          enable_plugins :query_plugin
+        end
+
+        class << self
+          # Formatted string specification template
+          # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+          def api_template = "/gem/%{period}/%{gem}"
+
+          def anchor_href_template = "https://rubygems.org/gems/%{gem}"
+
+          def label_text_template = "RubyGems Download Rank"
+        end
+      end
+    end
+  end
+end

data/lib/shields/badge/downloads/gem_total_downloads.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module Downloads
+      # Shield for RubyGem daily downloads
+      # # See: https://shields.io/badges/gem-total-downloads
+      class GemTotalDownloads < Base
+        class PathDto < ::Castkit::DataObject
+          enable_plugins :path_plugin
+          required do
+            string :gem, ignore_nil: true
+          end
+        end
+
+        class QueryDto < ::Castkit::DataObject
+          enable_plugins :query_plugin
+        end
+
+        class << self
+          # Formatted string specification template
+          # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+          def api_template = "/gem/dt/%{gem}"
+
+          def anchor_href_template = "https://rubygems.org/gems/%{gem}"
+
+          def label_text_template = "RubyGems Total Downloads"
+        end
+      end
+    end
+  end
+end

data/lib/shields/badge/social/github_repo_stars.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module Social
+      # Shield for GitHub Repo Stars count
+      # See: https://shields.io/badges/git-hub-repo-stars
+      class GithubRepoStars < Base
+        class PathDto < ::Castkit::DataObject
+          enable_plugins :path_plugin
+          enable_plugins :github_repo_plugin
+        end
+
+        class QueryDto < ::Castkit::DataObject
+          enable_plugins :query_plugin
+        end
+
+        class << self
+          # Formatted string specification template
+          # See: https://ruby-doc.org/3.4.1/String.html#method-i-25
+          def api_template = "/github/stars/%{user}/%{repo}"
+
+          def anchor_href_template = "https:///github.com/%{user}/%{repo}/stargazers"
+
+          def label_text_template = "GitHub Stars"
+        end
+      end
+    end
+  end
+end

data/lib/shields/badge/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Shields
+  module Badge
+    module Version
+      VERSION = "1.0.0"
+    end
+  end
+end

data/lib/shields/badge.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# third party gems
+require "castkit"
+require "castkit/plugins"
+require "version_gem"
+
+# this gem
+# Template classes for shields.io badge generation
+require_relative "api_template"
+require_relative "anchor_href_template"
+require_relative "label_text_template"
+
+# Constants
+require_relative "categories"
+
+# Formatters
+require_relative "formatters/markdown"
+require_relative "formatters/image_src_url"
+
+# Serializers
+require_relative "serializers/camel_caser"
+
+# Plugins
+require_relative "plugins/git_branch_plugin"
+require_relative "plugins/github_repo_plugin"
+require_relative "plugins/query_plugin"
+require_relative "plugins/path_plugin"
+
+# Errors
+require_relative "errors/error"
+require_relative "errors/not_implemented"
+require_relative "errors/validation_error"
+
+# Core
+require_relative "badge/base"
+
+# Version
+require_relative "badge/version"
+
+# Badges
+# Individually required as they are registered
+# Or by requiring "shields/register_all"
+module Shields
+  module Badge
+    SAFE_TO_CLASSIFY = /\A[\p{LOWERCASE-LETTER}\p{DECIMAL-NUMBER}_]{1,511}\Z/
+    SAFE_TO_UNDERSCORE = /\A[\p{UPPERCASE-LETTER}\p{LOWERCASE-LETTER}\p{DECIMAL-NUMBER}]{1,256}\Z/
+    SUBBER_UNDER = /(\p{UPPERCASE-LETTER})/
+    INITIAL_UNDERSCORE = /^_/
+
+    def register_all
+      require_relative "register_all"
+    end
+    module_function :register_all
+
+    # Badges will be registered lazily, so that they can be used without loading the entire set.
+    def register(klass:)
+      raise Errors::Error, "Badge class must be a class, but is #{klass.class}" unless klass.is_a?(Class)
+
+      klass_name = klass.name.split("::").last
+      method_name = classy_to_underscore(klass_name)
+      define_singleton_method(method_name) do |**kwargs|
+        as = kwargs.delete(:as) || :markdown
+        formatter_module = case as.to_sym
+        # Please write an rSt formatter and submit a PR!
+        # Please write an AsciiDoc formatter and submit a PR!
+        # Please write an HTML formatter and submit a PR!
+        when :image_src_url, :markdown
+          Shields::Formatters.const_get(underscore_to_classy(as))
+        else
+          raise Errors::Error, "Unknown formatter: #{as}"
+        end
+        badge = klass.new(**kwargs)
+        badge.format(formatter_module)
+      end
+    end
+    module_function :register
+
+    def register_by_method_name(method_name:, category: nil)
+      # send it through the conversion to ensure it is clean
+      # IMPORTANT: use the same logic as respond_to_missing?
+      klass_name, clean_method = clean_method_name(method_name)
+      # This code should be unreachable, but it is here for completeness
+      # :nocov:
+      return false unless klass_name && (clean_method == method_name.to_s)
+      # :nocov:
+
+      category ||= Categories[clean_method]
+      # method_name must also match the file name
+      file_parts = ["badge", category, clean_method].compact
+      file_extension = File.join(*file_parts)
+      begin
+        require_relative(file_extension)
+
+        klass = Kernel.const_get("Shields::Badge::#{underscore_to_classy(category)}::#{klass_name}")
+
+        return register(klass:)
+      rescue LoadError => error
+        if error.message.include?(file_extension)
+          # rescue is so method_missing, which likely called this method, can do its thing.
+          warn("Could not load #{file_extension} for #{klass_name} in #{__FILE__}:#{__LINE__}.\n")
+        else
+          # This code should be unreachable, but it is here for completeness
+          # :nocov:
+          raise error
+          # :nocov:
+        end
+      end
+      false
+    end
+    module_function :register_by_method_name
+
+    def method_missing(method_name, **kwargs, &block)
+      super unless register_by_method_name(method_name:)
+
+      send(method_name, **kwargs)
+    end
+    module_function :method_missing
+
+    def respond_to_missing?(method_name, include_private = false)
+      klass_name, clean_method = clean_method_name(method_name)
+      klass_name && (clean_method == method_name.to_s) || super
+    end
+    module_function :respond_to_missing?
+
+    private
+
+    def clean_method_name(method_name)
+      safe_classy = underscore_to_classy(method_name)
+      [safe_classy, classy_to_underscore(safe_classy)]
+    end
+    module_function :clean_method_name
+
+    def underscore_to_classy(underscored)
+      safe = underscored[SAFE_TO_CLASSIFY]
+      raise Errors::Error, "Invalid badge name must match #{SAFE_TO_CLASSIFY}: #{safe} (#{safe.class}) != #{underscored[0..510]} (#{underscored.class})" unless safe == underscored.to_s
+
+      safe.to_s.split("_").map(&:capitalize).join("")
+    end
+    module_function :underscore_to_classy
+
+    def classy_to_underscore(string)
+      safe = string[SAFE_TO_UNDERSCORE]
+      raise Errors::Error, "Invalid badge class must match #{SAFE_TO_UNDERSCORE}: #{safe} (#{safe.class}) != #{string[0..255]} (#{string.class})" unless safe == string.to_s
+
+      underscored = safe.gsub(SUBBER_UNDER) { "_#{$1}" }
+      shifted_leading_underscore = underscored.sub(INITIAL_UNDERSCORE, "")
+      shifted_leading_underscore.downcase
+    end
+    module_function :classy_to_underscore
+  end
+end
+
+Shields::Badge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/shields/categories.rb

@@ -0,0 +1,17 @@
+module Shields
+  module Categories
+    CATEGORIES = {
+      "github_commits_since_latest_release" => "activity",
+      "github_branch_check_runs" => "build",
+      "coveralls" => "code_coverage",
+      "gem_download_rank" => "downloads",
+      "gem_total_downloads" => "downloads",
+      "github_repo_stars" => "social",
+    }
+
+    def [](name)
+      CATEGORIES[name]
+    end
+    module_function :[]
+  end
+end

data/lib/shields/errors/error.rb

@@ -0,0 +1,5 @@
+module Shields
+  module Errors
+    class Error < StandardError; end
+  end
+end

data/lib/shields/errors/not_implemented.rb

@@ -0,0 +1,5 @@
+module Shields
+  module Errors
+    class NotImplemented < Error; end
+  end
+end

data/lib/shields/errors/validation_error.rb

@@ -0,0 +1,5 @@
+module Shields
+  module Errors
+    class ValidationError < Error; end
+  end
+end

data/lib/shields/formatters/image_src_url.rb

@@ -0,0 +1,17 @@
+module Shields
+  module Formatters
+    module ImageSrcUrl
+      SIGNATURE = %i(img_src_url)
+
+      def call(img_src_url:)
+        img_src_url
+      end
+      module_function :call
+
+      def signature
+        SIGNATURE
+      end
+      module_function :signature
+    end
+  end
+end

data/lib/shields/formatters/markdown.rb

@@ -0,0 +1,18 @@
+module Shields
+  module Formatters
+    module Markdown
+      SIGNATURE = %i(label_text img_src_url anchor_href_url)
+
+      def call(label_text:, img_src_url:, anchor_href_url:)
+        "[![%{label_text}](%{img_src_url})](%{anchor_href_url})" %
+          {label_text:, img_src_url:, anchor_href_url:}
+      end
+      module_function :call
+
+      def signature
+        SIGNATURE
+      end
+      module_function :signature
+    end
+  end
+end

data/lib/shields/label_text_template.rb

@@ -0,0 +1,11 @@
+module Shields
+  class LabelTextTemplate
+    def initialize(msg)
+      @msg = msg
+    end
+
+    def call(**args)
+      @msg % args
+    end
+  end
+end

data/lib/shields/plugins/git_branch_plugin.rb

@@ -0,0 +1,17 @@
+module Shields
+  module Plugins
+    module GitBranchPlugin
+      class << self
+        def setup!(klass)
+          klass.required do
+            klass.string(:branch)
+          end
+        end
+      end
+    end
+  end
+end
+
+Castkit.configure do |config|
+  config.register_plugin(:git_branch_plugin, Shields::Plugins::GitBranchPlugin)
+end

data/lib/shields/plugins/github_repo_plugin.rb

@@ -0,0 +1,18 @@
+module Shields
+  module Plugins
+    module GithubRepoPlugin
+      class << self
+        def setup!(klass)
+          klass.required do
+            klass.string(:user)
+            klass.string(:repo)
+          end
+        end
+      end
+    end
+  end
+end
+
+Castkit.configure do |config|
+  config.register_plugin(:github_repo_plugin, Shields::Plugins::GithubRepoPlugin)
+end

data/lib/shields/plugins/path_plugin.rb

@@ -0,0 +1,11 @@
+module Shields
+  module Plugins
+    module PathPlugin
+      # Currently, there are no shared behaviors of Path Parameters that would make sense here.
+    end
+  end
+end
+
+Castkit.configure do |config|
+  config.register_plugin(:path_plugin, Shields::Plugins::PathPlugin)
+end