how_is 24.0.0 → 25.0.0

data/lib/how_is/sources/github/issues.rb

@@ -1,274 +1,125 @@
 # frozen_string_literal: true
 
-require "how_is/version"
+require "how_is/date_time_helpers"
 require "how_is/sources/github"
 require "how_is/sources/github_helpers"
+require "how_is/sources/github/issue_fetcher"
+require "how_is/template"
 require "date"
 
-module HowIs::Sources
-  class Github
-    class Issues
-      include HowIs::Sources::GithubHelpers
-
-      TERMINATE_GRAPHQL_LOOP = :terminate_graphql_loop
-
-      def initialize(repository, start_date, end_date)
-        @repository = repository
-        @user, @repo = repository.split("/", 2)
-        @start_date = start_date
-        @end_date = end_date
-      end
-
-      def url(values = {})
-        defaults = {
-          "is" => singular_type,
-          "created" => "#{@start_date}..#{@end_date}",
-        }
-        values = defaults.merge(values)
-        raw_query = values.map { |k, v|
-          [k, v].join(":")
-        }.join(" ")
-
-        query = CGI.escape(raw_query)
-
-        "https://github.com/#{@repository}/#{url_suffix}?q=#{query}"
-      end
-
-      def average_age
-        average_age_for(data)
-      end
-
-      def oldest
-        oldest_for(data) || {}
-      end
-
-      def newest
-        newest_for(data) || {}
-      end
-
-      def summary
-        number_open = to_a.length
-        pretty_number =
-          pluralize(pretty_type, number_open, zero_is_no: true)
+module HowIs
+  module Sources
+    class Github
+      ##
+      # Fetches various information about GitHub Issues.
+      class Issues
+        include HowIs::DateTimeHelpers
+        include HowIs::Sources::GithubHelpers
+
+        attr_reader :config, :start_date, :end_date, :cache
+
+        # @param repository [String] GitHub repository name, of the format user/repo.
+        # @param start_date [String] Start date for the report being generated.
+        # @param end_date   [String] End date for the report being generated.
+        # @param cache      [Cacheable] Instance of HowIs::Cacheable to cache API calls
+        def initialize(config, start_date, end_date, cache)
+          @config = config
+          @cache = cache
+          @repository = config["repository"]
+          raise "#{self.class}.new() got nil repository." if @repository.nil?
+          @start_date = start_date
+          @end_date = end_date
+        end
 
-        "There #{are_or_is(number_open)} <a href=\"#{url}\">#{pretty_number} open</a>."
-      end
+        def url(values = {})
+          defaults = {
+            "is" => singular_type,
+            "created" => "#{@start_date}..#{@end_date}",
+          }
+          values = defaults.merge(values)
+          raw_query = values.map { |k, v|
+            [k, v].join(":")
+          }.join(" ")
 
-      def to_html
-        summary_ = "<p>#{summary}</p>"
+          query = CGI.escape(raw_query)
 
-        return summary_ if to_a.empty?
+          "https://github.com/#{@repository}/#{url_suffix}?q=#{query}"
+        end
 
-        template_data = {
-          summary: summary_,
-          average_age: average_age,
-          type: type,
-          pretty_type: pretty_type,
+        def average_age
+          average_age_for(data)
+        end
 
-          oldest_link: oldest["url"],
-          oldest_date: pretty_date(oldest["createdAt"]),
+        def oldest
+          result = oldest_for(data)
+          return {} if result.nil?
 
-          newest_link: newest["url"],
-          newest_date: pretty_date(newest["createdAt"]),
-        }
+          result["date"] = pretty_date(result["createdAt"])
 
-        Kernel.format(HowIs.template("issues_or_pulls_partial.html_template"), template_data)
-      end
+          result
+        end
 
-      # TODO: Clean up Issues Per Label stuff, or replace it with different functionality.
+        def newest
+          result = newest_for(data)
+          return {} if result.nil?
 
-      def issues_per_label
-        ipl = with_label_links(num_with_label(data), @repository)
-        number_with_no_label = num_with_no_label(data)
+          result["date"] = pretty_date(result["createdAt"])
 
-        if number_with_no_label > 0
-          ipl["(No label)"] = {
-            "name" => "(No label)",
-            "total" => number_with_no_label,
-          }
+          result
         end
 
-        ipl
-      end
-
-      HTML_GRAPH_ROW = <<-EOF
-  <tr>
-    <td style="width: %{label_width}">%{label_text}</td>
-    <td><span class="fill" style="width: %{percentage}%%">%{link_text}</span></td>
-  </tr>
-      EOF
+        def summary
+          number_open = to_a.length
+          pretty_number = pluralize(pretty_type, number_open, zero_is_no: false)
+          was_were = (number_open == 1) ? "was" : "were"
 
-      def issues_per_label_html
-        ipl = issues_per_label
-
-        return "<p>There are no open issues to graph.</p>" if ipl.empty?
+          "<p>A total of <a href=\"#{url}\">#{pretty_number}</a> #{was_were} opened during this period.</p>"
+        end
 
-        biggest = ipl.map { |_label, info| info["total"] }.max
-        get_percentage = ->(number_of_issues) { number_of_issues * 100 / biggest }
+        def to_html
+          return summary if to_a.empty?
 
-        longest_label_length = ipl.map(&:first).map(&:length).max
-        label_width = "#{longest_label_length}ch"
+          HowIs::Template.apply("issues_or_pulls_partial.html", {
+            summary: summary,
+            average_age: average_age,
+            pretty_type: pretty_type,
 
-        parts = ipl.map { |label, info|
-          # TODO: Remove this hack to get around unlabeled issues not having a link.
-          label_text = label
-          label_url  = label_url_for(info["name"])
-          label_text = '<a href="' + label_url + '">' + label_text + '</a>'
+            oldest_link: oldest["url"],
+            oldest_date: oldest["date"],
 
-          Kernel.format(HTML_GRAPH_ROW, {
-            label_width: label_width,
-            label_text: label_text,
-            label_link: info["url"],
-            percentage: get_percentage.call(info["total"]),
-            link_text: info["total"].to_s,
+            newest_link: newest["url"],
+            newest_date: newest["date"],
           })
-        }
-
-        "<table class=\"horizontal-bar-graph\">\n" +
-        parts.join("\n") +
-        "\n</table>"
-      end
-
-      def to_a
-        obj_to_array_of_hashes(data)
-      end
-
-      private
-
-      def url_suffix
-        "issues"
-      end
-
-      def singular_type
-        "issue"
-      end
-
-      def type
-        singular_type + "s"
-      end
-
-      def pretty_type
-        "issue"
-      end
-
-      def data
-        return @data if instance_variable_defined?(:@data)
-
-        @data = []
-        return @data if last_cursor.nil?
-
-        after = nil
-        data = []
-        until after == TERMINATE_GRAPHQL_LOOP
-          after, data = fetch_issues(after, data)
         end
 
-        @data = data.select(&method(:issue_is_relevant?))
-      end
-
-      def issue_is_relevant?(issue)
-        if !issue["closedAt"].nil? && date_le(issue["closedAt"], @start_date)
-          false
-        else
-          date_ge(issue["createdAt"], @start_date) && date_le(issue["createdAt"], @end_date)
+        def to_a
+          obj_to_array_of_hashes(data)
         end
-      end
-
-      def graphql(query_string)
-        query = Okay::GraphQL.query(query_string)
-        headers = {bearer_token: HowIs::Sources::Github::ACCESS_TOKEN}
-        query.submit!(:github, headers).or_raise!.from_json
-      end
 
-      def last_cursor
-        return @last_cursor if instance_variable_defined?(:@last_cursor)
-
-        raw_data = graphql <<~QUERY
-          repository(owner: #{@user.inspect}, name: #{@repo.inspect}) {
-            #{type}(last: 1, orderBy:{field: CREATED_AT, direction: ASC}) {
-              edges {
-                cursor
-              }
-            }
-          }
-        QUERY
-
-        edges = raw_data.dig("data", "repository", type, "edges")
-        @last_cursor =
-          if edges.nil? || edges.empty?
-            nil
-          else
-            edges.last["cursor"]
-          end
-      end
-
-      def fetch_issues(after, data)
-        data ||= []
-        chunk_size = 100
-        after_str = ", after: #{after.inspect}" unless after.nil?
-
-        raw_data = graphql <<~QUERY
-          repository(owner: #{@user.inspect}, name: #{@repo.inspect}) {
-            #{type}(first: #{chunk_size}#{after_str}, orderBy:{field: CREATED_AT, direction: ASC}) {
-              edges {
-                cursor
-                node {
-                  number
-                  createdAt
-                  closedAt
-                  updatedAt
-                  state
-                  title
-                  url
-                  labels(first: 100) {
-                    nodes {
-                      name
-                    }
-                  }
-                }
-              }
-            }
-          }
-        QUERY
-
-        edges = raw_data.dig("data", "repository", type, "edges")
-
-        current_last_cursor = edges.last["cursor"]
-
-        unless edges.nil?
-          new_data = edges.map { |issue|
-            node = issue["node"]
-            node["labels"] = node["labels"]["nodes"]
-
-            node
-          }
-
-          data += new_data
+        def type
+          singular_type + "s"
         end
 
-        if current_last_cursor == last_cursor
-          current_last_cursor = TERMINATE_GRAPHQL_LOOP
+        def pretty_type
+          "issue"
         end
 
-        [current_last_cursor, data]
-      end
-
-      def date_le(left, right)
-        left  = str_to_dt(left)
-        right = str_to_dt(right)
+        private
 
-        left <= right
-      end
+        def url_suffix
+          "issues"
+        end
 
-      def date_ge(left, right)
-        left  = str_to_dt(left)
-        right = str_to_dt(right)
+        def singular_type
+          "issue"
+        end
 
-        left >= right
-      end
+        def data
+          return @data if instance_variable_defined?(:@data)
 
-      def str_to_dt(str)
-        DateTime.parse(str)
+          fetcher = IssueFetcher.new(self)
+          @data = fetcher.data
+        end
       end
     end
   end

data/lib/how_is/sources/github/pulls.rb

@@ -1,27 +1,28 @@
 # frozen_string_literal: true
 
-require "how_is/version"
-require "how_is/sources/github"
-require "how_is/sources/github_helpers"
-require "date"
+require "how_is/sources/github/issues"
 
-module HowIs::Sources
-  class Github
-    class Pulls < Issues
-      def url_suffix
-        "pulls"
-      end
+module HowIs
+  module Sources
+    class Github
+      ##
+      # Fetches various information about GitHub Pull Requests
+      class Pulls < Issues
+        def url_suffix
+          "pulls"
+        end
 
-      def singular_type
-        "pull"
-      end
+        def singular_type
+          "pull"
+        end
 
-      def type
-        "pullRequests"
-      end
+        def type
+          "pullRequests"
+        end
 
-      def pretty_type
-        "pull request"
+        def pretty_type
+          "pull request"
+        end
       end
     end
   end

data/lib/how_is/sources/github.rb

@@ -2,34 +2,56 @@
 
 require "how_is/version"
 require "how_is/sources"
-require "github_api"
 require "okay/graphql"
 
 module HowIs
   module Sources
     # Contains configuration information for GitHub-based sources.
     class Github
-      # An exception which is only raised if an environment variable
-      # is undefined.
-      class ConfigurationError < StandardError
-        def initialize(env_variable)
-          super("environment variable #{env_variable} not defined." \
-                  " See README.md for details.")
-        end
+      class ConfigError < StandardError
       end
 
-      # A GitHub Personal Access Token.
-      ACCESS_TOKEN = ENV["HOWIS_GITHUB_TOKEN"]
-      raise ConfigurationError, "HOWIS_GITHUB_TOKEN" if ACCESS_TOKEN.nil?
+      def initialize(config)
+        must_have_key!(config, "sources/github")
 
-      # "<github username>:<personal access token>"
-      BASIC_AUTH = ENV["HOWIS_BASIC_AUTH"]
-      raise ConfigurationError, "HOWIS_BASIC_AUTH" if BASIC_AUTH.nil?
+        @config = config["sources/github"]
 
-      # Used for the the Authorization header when talking to the
-      # GitHub API.
-      # https://developer.github.com/v4/guides/forming-calls/#communicating-with-graphql
-      AUTHORIZATION_HEADER = "bearer " + ACCESS_TOKEN
+        must_have_key!(@config, "username")
+        must_have_key!(@config, "token")
+      end
+
+      # Verify that +hash+ has a particular +key+.
+      #
+      # @raise [ConfigError] If +hash+ does not have the required +key+.
+      def must_have_key!(hash, key)
+        raise ConfigError, "Expected Hash, got #{hash.class}" unless hash.is_a?(Hash)
+        raise ConfigError, "Expected key `#{key}'" unless hash.has_key?(key)
+      end
+      private :must_have_key!
+
+      # The GitHub username used for authenticating with GitHub.
+      def username
+        @config["username"]
+      end
+
+      # A GitHub Personal Access Token which goes with +username+.
+      def access_token
+        @config["token"]
+      end
+
+      # A string containing both the GitHub username and access token,
+      # used in instances where we use Basic Auth.
+      def basic_auth
+        "#{username}:#{access_token}"
+      end
+
+      # Submit a GraphQL query, and convert it from JSON to a Ruby object.
+      def graphql(query_string)
+        Okay::GraphQL.query(query_string)
+          .submit!(:github, {bearer_token: access_token})
+          .or_raise!
+          .from_json
+      end
     end
   end
 end

data/lib/how_is/sources/github_helpers.rb

@@ -5,46 +5,13 @@ require "date"
 
 module HowIs
   module Sources
+    ##
+    # Helper functions used by GitHub-related sources.
     module GithubHelpers
       def obj_to_array_of_hashes(object)
         object.to_a.map(&:to_h)
       end
 
-      # Given an Array of issues or pulls, return a Hash specifying how many
-      # issues or pulls use each label.
-      def num_with_label(issues_or_pulls)
-        # Returned hash maps labels to frequency.
-        # E.g., given 10 issues/pulls with label "label1" and 5 with label "label2",
-        # {
-        #   "label1" => 10,
-        #   "label2" => 5
-        # }
-
-        hash = Hash.new(0)
-        issues_or_pulls.each do |iop|
-          next unless iop["labels"]
-
-          iop["labels"].each do |label|
-            hash[label["name"]] += 1
-          end
-        end
-        hash
-      end
-
-      # Returns the number of issues with no label.
-      def num_with_no_label(issues)
-        issues.select { |x| x["labels"].empty? }.length
-      end
-
-      # Given an Array of dates, average the timestamps and return the date that
-      # represents.
-      def average_date_for(issues_or_pulls)
-        timestamps = issues_or_pulls.map { |iop| DateTime.parse(iop["createdAt"]).strftime("%s").to_i }
-        average_timestamp = timestamps.reduce(:+) / issues_or_pulls.length
-
-        DateTime.strptime(average_timestamp.to_s, "%s")
-      end
-
       # Given an Array of issues or pulls, return the average age of them.
       # Returns nil if no issues or pulls are provided.
       def average_age_for(issues_or_pulls)
@@ -53,19 +20,12 @@ module HowIs
         ages = issues_or_pulls.map { |iop| time_ago_in_seconds(iop["createdAt"]) }
         average_age_in_seconds = ages.reduce(:+) / ages.length
 
-        values = period_pairs_for(average_age_in_seconds).reject { |(v, _)| v.zero? }.map { |(v, k)|
-          k += "s" if v != 1
-          [v, k]
-        }
-
-        most_significant = values[0, 2].map { |x| x.join(" ") }
+        values =
+          period_pairs_for(average_age_in_seconds) \
+            .reject { |(v, _)| v.zero? } \
+            .map { |(v, k)| pluralize(k, v) }
 
-        value =
-          if most_significant.length < 2
-            most_significant.first
-          else
-            most_significant.join(" and ")
-          end
+        value = values[0, 2].join(" and ")
 
         "approximately #{value}"
       end
@@ -90,48 +50,13 @@ module HowIs
         sort_iops_by_created_at(issues_or_pulls).last
       end
 
-      # Given an issue or PR, returns the date it was created.
-      def date_for(issue_or_pull)
-        DateTime.parse(issue_or_pull["createdAt"])
-      end
-
-      def label_url_for(label_name)
-        if label_name == "(No label)"
-          url({"no"=>"label"})
-        else
-          url({"label"=>label_name})
-        end
-      end
-
       private
 
-      # Takes an Array of labels, and returns amodified list that includes links
-      # to each label.
-      def with_label_links(labels, repository)
-        labels.map { |label, num_issues|
-          label_link = "https://github.com/#{repository}/issues?q=" + CGI.escape("is:open is:issue label:\"#{label}\"")
-
-          [label, {"link" => label_link, "total" => num_issues}]
-        }.to_h
-      end
-
       # Returns how many seconds ago a date (as a String) was.
       def time_ago_in_seconds(x)
         DateTime.now.strftime("%s").to_i - DateTime.parse(x).strftime("%s").to_i
       end
 
-      def issue_or_pull_to_hash(iop)
-        return nil if iop.nil?
-
-        ret = {}
-
-        ret["html_url"] = iop["html_url"]
-        ret["number"] = iop["number"]
-        ret["date"] = date_for(iop)
-
-        ret
-      end
-
       SECONDS_IN_A_YEAR = 31_556_926
       SECONDS_IN_A_MONTH = 2_629_743
       SECONDS_IN_A_WEEK = 604_800
@@ -165,14 +90,6 @@ module HowIs
         "#{number_str} #{string}#{(number == 1) ? '' : 's'}"
       end
 
-      def are_or_is(number)
-        if number == 1
-          "is"
-        else
-          "are"
-        end
-      end
-
       def pretty_date(date_or_str)
         if date_or_str.is_a?(DateTime)
           date = datetime_or_str
@@ -182,7 +99,7 @@ module HowIs
           raise ArgumentError, "expected DateTime or String, got #{date_or_str.class}"
         end
 
-        date.strftime("%b %_d, %Y")
+        date.strftime("%b %d, %Y")
       end
     end
   end

data/lib/how_is/sources.rb

@@ -3,6 +3,8 @@
 require "how_is/version"
 
 module HowIs
+  ##
+  # Various information sources used by HowIs.
   module Sources
     # Simply for creating a namespace.
   end

data/lib/how_is/template.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "how_is/version"
+require "okay/template"
+
+module HowIs
+  # Provides basic templating functionality.
+  Template = Okay::Template.new(File.expand_path("./templates/", __dir__))
+end

data/lib/how_is/templates/contributions_partial.html

@@ -0,0 +1 @@
+%{start_text}, %{user}/%{repo} gained <a href="%{compare_url}">%{new_commits}</a>, contributed by %{authors}. There %{additions_count_str} %{additions} and %{deletions} across %{changed_files}.

data/lib/how_is/templates/new_contributors_partial.html

@@ -0,0 +1,5 @@
+<p>There %{was_were} %{number_of_new_contributors} new contributor%{contributor_s} during this report period.</p>
+
+<ul>
+%{list_items}
+</ul>

data/lib/how_is/templates/{report.html_template → report.html}

@@ -9,14 +9,6 @@
         max-width: 72ch;
         margin: auto;
       }
-      .horizontal-bar-graph {
-        position: relative;
-        width: 100%%; /* lol Kernel.format() disapproves. */
-      }
-      .horizontal-bar-graph .fill {
-        display: inline-block;
-        background: #CCC;
-      }
     </style>
   </head>
   <body>