gems_bond 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc62800e859ce8dcf0015580a685bfaf8b5410c69843acae6d49e24fae011c4e
-  data.tar.gz: 6ee8416eade996316171af619d7e7fd6f14d3c82817f299c92c793902b5b6076
+  metadata.gz: 2cafc096896bf8383fde404d0c47020e4b8f9b1fe49c5cabfc1e8357c766682e
+  data.tar.gz: 48b00b4c32c30eafa88fa8c839b8ad9c7ddab251420e501c6010853062064047
 SHA512:
-  metadata.gz: d82f72f550a6be300e0d5ca5483b10ef8a7070e10912c89e2900675bdafd712ba6c4014728a5641f7789666d84da8ec126ea2c2b4e0d8a155b7134f68261f952
-  data.tar.gz: ae59181cbfbf9cff164a4c7c5776ccea3ef5c14a773a18d8ae5706be553fc61eff0b9d2a64b54bd11adeb7da8516152cbca5a1cc78daa04f292fdf43391618bb
+  metadata.gz: bfe4e248242f9609bad37d5b72cd5a6ef1557ec59039729c76b5f5658f08dea6dcf9ab5c563bab778c27de15688ad77b3f7d9cbea4e569c22f0bfb84b3aa3fd2
+  data.tar.gz: b46f8529d54c8a3b3e6de88f9951bb78c61e2747bb8033de3f712556a874d58548428aa1d2fea8216997487e9962f906b112c1c268964d426f4d2a68b27a5308

data/lib/gems_bond.rb

@@ -5,11 +5,12 @@ require "gems_bond/railtie" if defined?(Rails)
 
 # Gem module
 module GemsBond
-  class Error < StandardError; end
-
   class << self
     attr_accessor :configuration
 
+    # Configures Gems Bond
+    # @return GemsBond::Configuration
+    # @yieldparam [Proc] configuration to apply
     def configure
       self.configuration ||= Configuration.new
       yield(configuration)

data/lib/gems_bond/configuration.rb

@@ -5,6 +5,8 @@ module GemsBond
   class Configuration
     attr_accessor :github_token
 
+    # Initializes the configuration
+    # @return [GemsBond::Configuration]
     def initialize
       @github_token = nil
     end

data/lib/gems_bond/{examination_helper.rb → examination.rb}

@@ -1,16 +1,25 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 module GemsBond
   # Examines gem sanity
-  module ExaminationHelper
+  module Examination
     SCORES = YAML.safe_load(File.read(File.join(File.dirname(__FILE__), "scores.yml")))
     BOUNDARIES = SCORES["boundaries"]
     RESULTS = SCORES["results"]
 
-    def version_gap
-      memoize(:version_gap) { calculate_version_gap }
-    end
+    # @!method activity_score
+    # Returns activity score
+    # @return [Integer, nil] in [0, 1] (memoized)
+
+    # @!method popularity_score
+    # Returns popularity score
+    # @return [Integer, nil] in [0, 1] (memoized)
 
+    # @!method average_score
+    # Returns average score
+    # @return [Integer, nil] in [0, 1] (memoized)
     RESULTS.each do |result, values|
       define_method("#{result}_score") do
         memoize("#{result}_score") do
@@ -27,6 +36,9 @@ module GemsBond
 
     # Scores getters and calculation
 
+    # For each inspected data, generate two methods:
+    # - <data>_score that memoizes the calculated score
+    # - calculate_<data>_score that calculates the score and returns [Integer, nil] in [0, 1]
     BOUNDARIES.each_key do |key|
       # create a _score getter for each key
       define_method("#{key}_score") do
@@ -61,6 +73,15 @@ module GemsBond
       end
     end
 
+    # Returns a score with a logarithmic approach
+    # @param value [Float] the value for inspected data
+    # @param comparison [Numeric] the value giving the maximal score (1)
+    # @returns [Float]
+    # @example
+    #   soften(10.to_f,100.to_f) #=> 0.46
+    # The idea is that a gem with half as much stars
+    #   than rails gem (which is very high and stands for comparison here)
+    #   should get a very high score but still be behind rails itself
     def soften(value, comparison)
       # returns a shaped curve
       sigmoid = ->(x) { 1 / (1 + Math.exp(-x * 10)) }
@@ -69,8 +90,11 @@ module GemsBond
       (sigmoid.call(value / comparison) - 0.5) * 2
     end
 
-    # --- COMPUTE
-
+    # Returns an average after including weight for each value
+    # @param scores [Array<Array<Float, Integer>>] each hash looks like [value, weight]
+    # @returns [Float]
+    # @example
+    #   weighted_average([[4.0, 2], [1.0, 3]]) #=> 2.2
     def weighted_average(scores)
       acc = 0
       weight = 0
@@ -85,17 +109,5 @@ module GemsBond
 
       acc / weight
     end
-
-    # --- VERSION STATUS
-
-    def calculate_version_gap
-      return unless version && versions
-
-      index = versions.index { |v| v[:number] == version }
-      return unless index
-
-      gap = versions[0..index].count { |v| !v[:prerelease] } - 1
-      gap.positive? ? gap : 0
-    end
   end
 end

data/lib/gems_bond/fetchers/fetcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "octokit"
+
+module GemsBond
+  module Fetchers
+    class NotStartedError < StandardError; end
+
+    # Fetches data
+    class Fetcher
+      # Initializes an instance
+      # @param param [Object] Fetcher dependent
+      # @return [GemsBond::Fetchers::Fetcher]
+      def initialize(param); end
+
+      # Starts the service and returns self
+      # @note rescue connection errors with nil
+      def start
+        @started = true
+      end
+
+      # Starts the service and returns self
+      # @note rescue connection errors with nil
+      def stop
+        @started = false
+      end
+
+      # Is the service started?
+      def started?
+        @started
+      end
+    end
+  end
+end

data/lib/gems_bond/{fetcher → fetchers}/github.rb

@@ -1,58 +1,79 @@
 # frozen_string_literal: true
 
 require "octokit"
+require "gems_bond/fetchers/fetcher"
 
 module GemsBond
-  module Fetcher
+  module Fetchers
     # Fetches data from GitHub
-    class Github
+    class Github < Fetcher
+      # GitHub repository pattern, e.g.: "https://github.com/BigBigDoudou/gems_bond"
       REPOSITORY_REGEX = %r{https?://github.com/(?<repository>.*/.*)}.freeze
 
       class << self
+        # Validates that `url` matches GitHub repository URL
         def valid_url?(url)
           url&.match?(REPOSITORY_REGEX)
         end
       end
 
+      # Initializes an instance
+      # @param url [String] URL of the GitHub repository
+      # @return [GemsBond::Fetchers::Github]
       def initialize(url)
+        super(url)
         @url = url
       end
 
-      def source
-        "github"
-      end
-
+      # Starts the service
+      # @return [Boolean]
+      # @note rescue connection errors with nil
       def start
+        super
         parse_url
         login
+        # ensure repository exists (otherwise it raises Octokit error)
         set_repository
-        self
       rescue Octokit::Unauthorized, Octokit::InvalidRepository, Octokit::NotFound
-        nil
+        stop
       end
 
+      # Returns number of forks
+      # @return [Integer]
       def forks_count
         @repository["forks"]
       end
 
+      # Returns number of stars
+      # @return [Integer]
       def stars_count
         @repository["watchers"]
       end
 
+      # Returns number of contributors
+      # @return [Integer]
+      # @note GitHub API does not provide this number out of the box
+      #   so we fetch all repository contributors and paginate with 1 per page
+      #   thus the last page (from headers) should equal the number of contributors
       def contributors_count
         client = Octokit::Client.new(access_token: token, per_page: 1)
         client.contributors(@repository_path)
         response = client.last_response
         links = response.headers[:link]
+        # e.g.:  "[...] <https://api.github.com/repositories/8514/contributors?per_page=1&page=377>; rel=\"last\""
         return 0 unless links
 
-        Integer(links.match(/.*page=(?<last>\d+)>; rel="last"/)[:last], 10)
+        Integer(links.match(/.*per_page=1&page=(?<last>\d+)>; rel="last"/)[:last], 10)
       end
 
+      # Returns number of open issues
+      # @return [Integer]
       def open_issues_count
         @repository["open_issues"]
       end
 
+      # Returns date of last commit (on main branch)
+      # @return [Date]
       def last_commit_date
         date = client.commits(@repository_path).first[:commit][:committer][:date]
         return unless date
@@ -60,12 +81,16 @@ module GemsBond
         Date.parse(date.to_s)
       end
 
+      # Returns number of days since last commit
+      # @return [Date]
       def days_since_last_commit
         return unless last_commit_date
 
-        Date.today - last_commit_date
+        Integer(Date.today - last_commit_date)
       end
 
+      # Returns size of the lib directory
+      # @return [Integer]
       def lib_size
         contents_size = dir_size("lib")
         return unless contents_size
@@ -78,6 +103,9 @@ module GemsBond
 
       private
 
+      # Parses url to find out repository path
+      # @return [String]
+      # @raise Octokit::InvalidRepository if the url pattern is invalid
       def parse_url
         matches = @url.match(REPOSITORY_REGEX)
         raise Octokit::InvalidRepository unless matches
@@ -86,28 +114,44 @@ module GemsBond
         @repository_path = "#{path[0]}/#{path[1]}"
       end
 
+      # Logs with client
+      # @return [String] GitHub'username
       def login
+        return unless token
+
         @login ||= client.user.login
       end
 
+      # Initializes a client
+      # @return [Octokit::Client]
       def client
         Octokit::Client.new(access_token: token)
       end
 
+      # Returns token from configuration
+      # @return [String, nil]
       def token
         GemsBond.configuration&.github_token
       end
 
+      # Returns repository object
+      # @return [Sawyer::Resource]
       def set_repository
         @repository = client.repo(@repository_path)
       end
 
+      # Returns size of the given directory
+      # @param dir_path [String] path to the directory, e.g.: "lib/devise/strategies"
+      # @return [Integer]
+      # @note sum size of each subdirectories recursively
       def dir_size(dir_path)
         contents = client.contents(@repository_path, path: dir_path)
+        # starts accumulator with size of files
         acc =
           contents
           .select { |content| content[:type] == "file" }
           .sum { |content| content[:size] }
+        # adds size of subdirectories to the accumulator, with recursion
         acc +=
           contents
           .select { |content| content[:type] == "dir" }

data/lib/gems_bond/fetchers/ruby_gems.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "gems"
+require "rubygems"
+require "gems_bond/fetchers/fetcher"
+
+module GemsBond
+  module Fetchers
+    # Fetches data from RubyGems
+    class RubyGems < Fetcher
+      # Initializes an instance
+      # @param name [String] name of the gem
+      # @return [GemsBond::Fetchers::RubyGems]
+      def initialize(name)
+        super(name)
+        @name = name
+      end
+
+      # Starts the service
+      # @return [Boolean]
+      # @note rescue connection errors with nil
+      def start
+        super
+        # ensure gem exists (otherwise it raises Gems error)
+        @info = Gems.info(@name)
+      rescue Gems::NotFound
+        stop
+      end
+
+      # Returns gem description
+      # @return [String]
+      def info
+        @info["info"]
+      end
+
+      # Returns number of downloads
+      # @return [Integer]
+      def downloads_count
+        Gems.total_downloads(@name)[:total_downloads]
+      end
+
+      # Returns source code URI
+      # @return [String]
+      def source_code_uri
+        @info["source_code_uri"]
+      end
+
+      # Returns versions data (number, date and if it is a prerelease)
+      # @return [Array<Hash>]
+      # @note each hash structure: { number: String, created_at: Date, prerelease: Boolean }
+      def versions
+        Gems.versions(@name).map do |version|
+          {
+            number: version["number"],
+            created_at: Date.parse(version["created_at"]),
+            prerelease: version["prerelease"]
+          }
+        end
+      end
+
+      # Returns last version number
+      # @return [String]
+      def last_version
+        versions&.first&.dig(:number)
+      end
+
+      # Returns last version date
+      # @return [Date]
+      def last_version_date
+        versions&.first&.dig(:created_at)
+      end
+
+      # Returns number of days since last version
+      # @return [Integer]
+      def days_since_last_version
+        return unless last_version_date
+
+        Integer(Date.today - last_version_date)
+      end
+    end
+  end
+end

data/lib/gems_bond/gem.rb

@@ -1,46 +1,164 @@
 # frozen_string_literal: true
 
-require "gems_bond/fetch_helper"
-require "gems_bond/examination_helper"
+require "gems_bond/helpers/concurrency_helper"
+require "gems_bond/fetchers/ruby_gems"
+require "gems_bond/fetchers/github"
+require "gems_bond/examination"
 
 module GemsBond
   # Handles gem data
   class Gem
-    include FetchHelper
-    include ExaminationHelper
+    include GemsBond::Helpers::ConcurrencyHelper
+    include GemsBond::Examination
 
-    def initialize(dependency)
+    attr_reader :unknown
+
+    RUBY_GEM_KEYS = %i[
+      days_since_last_version downloads_count info last_version last_version_date source_code_uri versions
+    ].freeze
+
+    GITHUB_KEYS = %i[
+      contributors_count days_since_last_commit forks_count last_commit_date open_issues_count stars_count
+    ].freeze
+
+    # Initializes an instance
+    # @param dependency [Bundler::Dependency]
+    # @param unknown [Boolean] is it a current dependency?
+    # @return [GemsBond::Gem]
+    def initialize(dependency, unknown: false)
       @dependency = dependency
+      @unknown = unknown
     end
 
+    # Is the gem hosted on RubyGems?
+    # @retun [Boolean]
+    def exist?
+      ruby_gems_fetcher.started?
+    end
+
+    # Returns name
+    # @return [String] (memoized)
     def name
       memoize(__method__) { @dependency.name }
     end
 
+    # Returns description
+    # @return [String] (memoized)
     def description
-      memoize(__method__) { @dependency.description }
+      memoize(__method__) do
+        unknown ? info : @dependency.to_spec.description
+      end
     end
 
+    # Returns used version
+    # @return [String] (memoized)
     def version
-      memoize(__method__) { @dependency.to_spec.version.to_s }
+      memoize(__method__) do
+        @dependency.to_spec.version.to_s unless unknown
+      end
     end
 
+    # Returns homepage
+    # @return [String] (memoized)
     def homepage
-      memoize(__method__) { @dependency.to_spec.homepage }
+      memoize(__method__) do
+        @dependency.to_spec.homepage unless unknown
+      end
     end
 
+    # Returns url
+    # @return [String]
     def url
       homepage || source_code_uri
     end
 
+    # Returns GitHub url if exist
+    # @return [String, nil]
     def github_url
-      return homepage if GemsBond::Fetcher::Github.valid_url?(homepage)
+      [homepage, source_code_uri].find do |url|
+        GemsBond::Fetchers::Github.valid_url?(url)
+      end
+    end
+
+    RUBY_GEM_KEYS.each do |key|
+      define_method(key) do
+        memoize(key) do
+          fetch(ruby_gems_fetcher, key)
+        end
+      end
+    end
+
+    GITHUB_KEYS.each do |key|
+      define_method(key) do
+        memoize(key) do
+          fetch(github_fetcher, key)
+        end
+      end
+    end
+
+    # Returns gap between installed and last released version, in days
+    # @return [Integer, nil] (memoized)
+    def version_gap
+      memoize(:version_gap) do
+        return unless version && versions
+
+        index = versions.index { |v| v[:number] == version }
+        return unless index
 
-      source_code_uri if GemsBond::Fetcher::Github.valid_url?(source_code_uri)
+        gap = versions[0..index].count { |v| !v[:prerelease] } - 1
+        gap.positive? ? gap : 0
+      end
+    end
+
+    # Fetches data from APIs
+    # @param concurrency [Boolean] should it be run concurrently?
+    # @param verbose [Boolean] should gem's name be stdout?
+    # @return [void]
+    def prepare_data(keys: nil, concurrency: false, verbose: false)
+      fetch_key = ->(key) { (keys.nil? || key.in?(keys)) && __send__(key) }
+      if concurrency
+        each_concurrently(RUBY_GEM_KEYS + GITHUB_KEYS, &fetch_key)
+      else
+        (RUBY_GEM_KEYS + GITHUB_KEYS).each(&fetch_key)
+      end
+      puts(name) if verbose
     end
 
     private
 
+    # Fetches the given data with the given fetcher
+    # @param fetcher [GemsBond::Fetchers]
+    # @param key [String]
+    # @return [Object, nil]
+    def fetch(fetcher, key)
+      return if fetcher.nil?
+      raise GemsBond::Fetchers::NotStartedError unless fetcher.started?
+
+      fetcher.public_send(key)
+    end
+
+    # Returns a started RubyGems fetcher
+    # @return [GemsBond::Fetchers::RubyGems, nil]
+    # @note #start is needed to ensure the fetcher works
+    def ruby_gems_fetcher
+      return @ruby_gems_fetcher if defined?(@ruby_gems_fetcher)
+
+      @ruby_gems_fetcher = GemsBond::Fetchers::RubyGems.new(name).tap(&:start)
+    end
+
+    # Returns a started GitHub fetcher
+    # @return [GemsBond::Fetchers::Github, nil]
+    # @note #start is needed to ensure the fetcher works (especially the token)
+    def github_fetcher
+      return @github_fetcher if defined?(@github_fetcher)
+
+      @github_fetcher = github_url && GemsBond::Fetchers::Github.new(github_url).tap(&:start)
+    end
+
+    # Memoizes the given key and apply the given block
+    # @param key [String] the instance variable key
+    # @yieldparam [Object] the value to memoize
+    # @return [Object]
     def memoize(key)
       return instance_variable_get("@#{key}") if instance_variable_defined?("@#{key}")