how_is 19.0.0 → 20.0.0

data/how_is.gemspec

@@ -19,10 +19,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "github_api", "~> 0.17.0"
+  spec.add_runtime_dependency "github_api", "~> 0.18.1"
   spec.add_runtime_dependency "contracts", "~> 0.16.0"
 
-  spec.add_runtime_dependency "tessellator-fetcher", "~> 5.0.2"
+  spec.add_runtime_dependency "okay", "~> 4.0.0"
 
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 11.2"
@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "webmock"
   spec.add_development_dependency "rubocop", "~> 0.49.1"
   spec.add_development_dependency "github_changelog_generator"
+  spec.add_development_dependency "pry"
 end

data/lib/how_is/cli.rb

@@ -3,9 +3,7 @@
 require "how_is"
 require "optparse"
 
-class HowIs::CLI
-  DEFAULT_REPORT_FILE = "report.#{HowIs::DEFAULT_FORMAT}".freeze
-
+module HowIs::CLI
   # Parent class of all exceptions raised in HowIs::CLI.
   class OptionsError < StandardError
   end
@@ -67,7 +65,7 @@ class HowIs::CLI
       end
 
       opts.on("--report REPORT_FILE",
-              "Output file for the report (valid extensions: #{HowIs.supported_formats.join(', ')}; default: #{DEFAULT_REPORT_FILE})") do |filename|
+              "Output file for the report (valid extensions: #{HowIs.supported_formats.join(', ')}; default: #{HowIs::DEFAULT_REPORT_FILE})") do |filename|
         options[:report] = filename
       end
 
@@ -115,8 +113,8 @@ class HowIs::CLI
       # If we get here, we're generating a report from the command line,
       # without using --from or --config.
 
-      # If --report isn't specified, default to DEFAULT_REPORT_FILE.
-      options[:report] ||= DEFAULT_REPORT_FILE
+      # If --report isn't specified, default to HowIs::DEFAULT_REPORT_FILE.
+      options[:report] ||= HowIs::DEFAULT_REPORT_FILE
 
       # If we can't export to the specified file, raise an exception.
       unless HowIs.can_export_to?(options[:report])

data/lib/how_is/frontmatter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "how_is/version"
+
+module HowIs
+  module Frontmatter
+    # Generates YAML frontmatter, as is used in Jekyll and other blog engines.
+    #
+    # E.g.,
+    #     generate_frontmatter({'foo' => "bar %{baz}"}, {'baz' => "asdf"})
+    # =>  "---\nfoo: bar asdf\n"
+    def self.generate(frontmatter, report_data)
+      return "" if frontmatter.nil?
+
+      frontmatter = convert_keys(frontmatter, :to_s)
+      report_data = convert_keys(report_data, :to_sym)
+
+      frontmatter = frontmatter.map { |k, v|
+        # Sometimes report_data has unused keys, which generates a warning, but
+        # we're okay with it.
+        v = silence_warnings { v % report_data }
+
+        [k, v]
+      }.to_h
+
+      YAML.dump(frontmatter) + "---\n\n"
+    end
+
+    # @example
+    #   convert_keys({'foo' => 'bar'}, :to_sym)
+    #   # => {:foo => 'bar'}
+    def self.convert_keys(data, method_name)
+      data.map { |k, v| [k.send(method_name), v] }.to_h
+    end
+    private_class_method :convert_keys
+
+    def self.silence_warnings(&_block)
+      old_verbose = $VERBOSE
+      $VERBOSE = nil # Disable warnings entirely.
+      yield
+    ensure
+      $VERBOSE = old_verbose
+    end
+    private_class_method :silence_warnings
+  end
+end

data/lib/how_is/report.rb

@@ -1,82 +1,78 @@
 # frozen_string_literal: true
 
-require "date"
-require "pathname"
-
-class HowIs
-  # Raised when attempting to export to an unsupported format
-  class UnsupportedExportFormat < StandardError
-    def initialize(format)
-      super("Unsupported export format: #{format}")
-    end
-  end
+require "how_is/frontmatter"
+require "how_is/sources/github/contributions"
+require "how_is/sources/github/issues"
+require "how_is/sources/github/pulls"
+require "how_is/sources/travis"
 
-  # Report control class with class methods to make reports for an analysis
-  # or to save reports in files, or otherwise interact with the files.
+module HowIs
   class Report
-    require "how_is/report/json"
-    require "how_is/report/html"
+    def initialize(repository, end_date)
+      @repository = repository
+      @end_date = end_date
 
-    ##
-    # Export a report to a file.
-    def self.export_file(analysis, file)
-      format = file.split(".").last
-      report = get_report_class(format).new(analysis)
-
-      report.export_file(file)
+      @gh_contributions = HowIs::Sources::Github::Contributions.new(repository, end_date)
+      @gh_issues        = HowIs::Sources::Github::Issues.new(repository, end_date)
+      @gh_pulls         = HowIs::Sources::Github::Pulls.new(repository, end_date)
+      @travis           = HowIs::Sources::Travis.new(repository, end_date)
     end
 
-    ##
-    # Export a report to a String.
-    def self.export(analysis, format = HowIs::DEFAULT_FORMAT)
-      report = get_report_class(format).new(analysis)
+    def to_h(frontmatter_data = nil)
+      @report_hash ||= {
+        title: "How is #{@repository}?",
+        repository: @repository,
 
-      report.export
-    end
+        contributions_summary: @gh_contributions.to_html,
+        issues_summary: @gh_issues.to_html,
+        pulls_summary: @gh_pulls.to_html,
+        issues_per_label: @gh_issues.issues_per_label_html,
 
-    ##
-    # Saves given Report in given file.
-    #
-    # @param file [String,Pathname] Name of file to write to
-    # @param report [Report] Report to store
-    def self.save_report(file, report)
-      File.open(file, "w") do |f|
-        f.write report
-      end
-    end
+        issues: @gh_issues.to_a,
+        pulls: @gh_issues.to_a,
+
+        number_of_issues: @gh_issues.to_a.length,
+        number_of_pulls:  @gh_pulls.to_a.length,
+
+        average_issue_age: @gh_issues.average_age,
+        average_pull_age:  @gh_pulls.average_age,
 
-    ##
-    # Returns the report format for given filename.
-    #
-    # @param file [String] Filename of a report
-    #
-    # @return [String] Report format inferred from file name
-    def self.infer_format(file)
-      Pathname(file).extname.delete(".")
+        oldest_issue_link: @gh_issues.oldest[:link],
+        oldest_issue_date: @gh_issues.oldest[:creation_date],
+
+        newest_issue_link: @gh_issues.newest[:link],
+        newest_issue_date: @gh_issues.newest[:creation_date],
+
+        oldest_pull_link: @gh_pulls.oldest[:link],
+        oldest_pull_date: @gh_pulls.oldest[:creation_date],
+
+        travis_builds: @travis.builds.to_h,
+      }
+
+      frontmatter =
+        if frontmatter_data
+          HowIs::Frontmatter.generate(frontmatter_data, @report_hash)
+        else
+          ""
+        end
+
+      @report_hash.merge(frontmatter: frontmatter)
     end
 
-    ##
-    # Exports given +report+ to the format suitable for given +file+.
-    #
-    # @param file [String,Pathname]
-    # @param report [Report]
-    #
-    # @return [String] The rendered report
-    def self.to_format_based_on(file, report)
-      report_format = infer_format(file)
-
-      report.public_send("to_#{report_format}")
+    def to_html_partial(frontmatter = nil)
+      template_data = to_h(frontmatter)
+
+      Kernel.format(HowIs.template("report_partial.html_template"), template_data)
     end
 
-    # Given a format name (+format+), returns the corresponding <blah>Report
-    # class.
-    def self.get_report_class(format)
-      class_name = "#{format.capitalize}Report"
+    def to_html(frontmatter = nil)
+      template_data = to_h(frontmatter).merge({report: to_html_partial})
 
-      raise UnsupportedExportFormat, format unless HowIs.const_defined?(class_name)
+      Kernel.format(HowIs.template("report.html_template"), template_data)
+    end
 
-      HowIs.const_get(class_name)
+    def to_json(frontmatter = nil)
+      frontmatter.to_s + JSON.pretty_generate(to_h)
     end
-    private_class_method :get_report_class
   end
 end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "how_is/version"
+require "how_is/sources/github"
+require "how_is/sources/github_helpers"
+require "date"
+
+module HowIs::Sources
+  class Github
+    # Fetch information about who has contributed to a repository during a given
+    # period.
+    #
+    # Usage:
+    #
+    #     c = HowIs::Contributions.new(start_date: '2017-07-01', user: 'how-is', repo: 'how_is')
+    #     c.commits          #=> All commits during July 2017.
+    #     c.contributors #=> All contributors during July 2017.
+    #     c.new_contributors #=> New contributors during July 2017.
+    class Contributions
+      include HowIs::Sources::GithubHelpers
+
+      # Returns an object that fetches contributor information about a particular
+      # repository for a month-long period starting on +start_date+.
+      #
+      # @param repository [String] GitHub repository in the form of "user/repo".
+      # @param end_date [String] Date in the format YYYY-MM-DD. The last date
+      #                          to include commits from.
+      def initialize(repository, end_date)
+        @user, @repo = repository.split("/")
+        @github = HowIs.github
+
+        # IMPL. DETAIL: The external API uses "end_date" so it's clearer,
+        #               but internally we use "until_date" to match GitHub's API.
+
+        # NOTE: Use DateTime because it defaults to UTC and that's less gross
+        #       than trying to get Date to use UTC.
+        #
+        #       Not using UTC for this results in #compare_url giving different
+        #       results for different time zones, which makes it harder to test.
+        #
+        #       (I'm also guessing/hoping that GitHub's URLs use UTC.)
+        @until_date = DateTime.strptime(end_date, "%Y-%m-%d")
+
+        d = @until_date.day
+        m = @until_date.month
+        y = @until_date.year
+        @since_date = DateTime.new(y, m - 1, d)
+
+        @commit = {}
+        @stats = nil
+        @changed_files = nil
+      end
+
+      # Returns a list of contributors that have zero commits before the @since_date.
+      #
+      # @return [Hash{String => Hash}] Contributors keyed by email
+      def new_contributors
+        # author: GitHub login, name or email by which to filter by commit author.
+        @new_contributors ||= contributors.select do |email, _committer|
+          # Returns true if +email+ never wrote a commit for +@repo+ before +@since_date+.
+          @github.repos.commits.list(user: @user,
+                                    repo: @repo,
+                                    until: @since_date,
+                                    author: email).count.zero?
+        end
+      end
+
+      # @return [Hash{String => Hash}] Author information keyed by author's email.
+      def contributors
+        commits.map { |api_response|
+          [api_response.commit.author.email, api_response.commit.author.to_h]
+        }.to_h
+      end
+
+      def commits
+        @commits ||= begin
+          @github.repos.commits.list(user: @user,
+                                    repo: @repo,
+                                    since: @since_date).map { |c|
+            # The commits list endpoint doesn't include all commit data, e.g. stats.
+            # So, we make N requests here, where N == number of commits returned,
+            # and then we die a bit inside.
+            commit(c.sha)
+          }
+        end
+      end
+
+      def commit(sha)
+        @commit[sha] ||= @github.repos.commits.get(user: @user, repo: @repo, sha: sha)
+      end
+
+      def changes
+        if @stats.nil? || @changed_files.nil?
+          @stats = {
+            "total" => 0,
+            "additions" => 0,
+            "deletions" => 0,
+          }
+
+          @changed_files = []
+
+          commits.map do |commit|
+            @stats.keys.each do |key|
+              @stats[key] += commit.stats[key]
+            end
+
+            @changed_files += commit.files.map { |file| file["filename"] }
+          end
+
+          @changed_files = @changed_files.sort.uniq
+        end
+
+        {"stats" => @stats, "files" => @changed_files}
+      end
+
+      def changed_files
+        changes["files"]
+      end
+
+      def additions_count
+        changes["stats"]["additions"]
+      end
+
+      def deletions_count
+        changes["stats"]["deletions"]
+      end
+
+      def compare_url
+        since_timestamp = @since_date.to_time.to_i
+        until_timestamp = @until_date.to_time.to_i
+        "https://github.com/#{@user}/#{@repo}/compare/#{default_branch}@%7B#{since_timestamp}%7D...#{default_branch}@%7B#{until_timestamp}%7D" # rubocop:disable Metrics/LineLength
+      end
+
+      def default_branch
+        @default_branch ||= @github.repos.get(user: @user,
+          repo: @repo).default_branch
+      end
+
+      def to_html(start_text: nil)
+        # TODO: Pulse has information about _all_ branches. Do we want that?
+        #       If we do, we'd need to pass a branch name as the 'sha' parameter
+        #       to /repos/:owner/:repo/commits.
+        #       https://developer.github.com/v3/repos/commits/
+
+        start_text ||= "From #{pretty_date(@since_date)} through #{pretty_date(@until_date)}"
+
+        "#{start_text}, #{@user}/#{@repo} gained "\
+          "<a href=\"#{compare_url}\">#{pluralize('new commit', commits.length)}</a>, " \
+          "contributed by #{pluralize('author', contributors.length)}. There " \
+          "#{(additions_count == 1) ? 'was' : 'were'} " \
+          "#{pluralize('addition', additions_count)} and " \
+          "#{pluralize('deletion', deletions_count)} across " \
+          "#{pluralize('file', changed_files.length)}."
+      end
+      alias :summary :to_html # For backwards compatibility.
+
+      private
+
+      def pretty_date(date)
+        date.strftime("%b %d, %Y")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "how_is/version"
+require "how_is/sources/github"
+require "how_is/sources/github_helpers"
+require "date"
+
+module HowIs::Sources
+  class Github
+    class Issues
+      include HowIs::Sources::GithubHelpers
+
+      def initialize(repository, end_date)
+        @repository = repository
+        @user, @repo = repository.split("/", 2)
+      end
+
+      def url
+        "https://github.com/#{@repository}/#{type}"
+      end
+
+      def average_age
+        average_age_for(@data)
+      end
+
+      def oldest
+        fetch!
+        oldest_for(@data) || {}
+      end
+
+      def newest
+        fetch!
+        newest_for(@data) || {}
+      end
+
+      def summary
+        number_open = to_a.length
+        pretty_number =
+          pluralize(pretty_type, number_open, zero_is_no: true)
+
+        "There #{are_or_is(number_open)} <a href=\"#{url}\">#{pretty_number} open</a>."
+      end
+
+      def to_html
+        fetch!
+
+        summary_ = "<p>#{summary}</p>"
+
+        return summary_ if to_a.empty?
+
+        template_data = {
+          summary: summary_,
+          average_age: average_age,
+          type: type,
+          pretty_type: pretty_type,
+
+          oldest_link: oldest[:link],
+          oldest_date: pretty_date(oldest[:created_at]),
+
+          newest_link: newest[:link],
+          newest_date: pretty_date(newest[:created_at]),
+        }
+
+        Kernel.format(HowIs.template("issues_or_pulls_partial.html_template"), template_data)
+      end
+
+      # TODO: Clean up Issues Per Label stuff, or replace it with different functionality.
+
+      def issues_per_label
+        ipl = with_label_links(num_with_label(@data), @repository)
+        number_with_no_label = num_with_no_label(@data)
+
+        if number_with_no_label > 0
+          ipl["(No label)"] = {
+            "link"  => nil,
+            "total" => number_with_no_label,
+          }
+        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 issues_per_label_html
+        data = issues_per_label
+
+        return "<p>There are no open issues to graph.</p>" if data.empty?
+
+        biggest = data.map { |_label, info| info["total"] }.max
+        get_percentage = ->(number_of_issues) { number_of_issues * 100 / biggest }
+
+        longest_label_length = data.map(&:first).map(&:length).max
+        label_width = "#{longest_label_length}ch"
+
+        parts = data.map { |label, info|
+          # TODO: Remove this hack to get around unlabeled issues not having a link.
+          label_text = label
+          unless info["link"].nil?
+            label_text = '<a href="' + info["link"] + '">' + label_text + '</a>'
+          end
+
+          Kernel.format(HTML_GRAPH_ROW, {
+            label_width: label_width,
+            label_text: label_text,
+            label_link: info["link"],
+            percentage: get_percentage.call(info["total"]),
+            link_text: info["total"].to_s,
+          })
+        }
+
+        "<table class=\"horizontal-bar-graph\">\n" +
+        parts.join("\n") +
+        "\n</table>"
+      end
+
+      def to_a
+        fetch!
+        obj_to_array_of_hashes(@data)
+      end
+
+      private
+
+      def type
+        "issues"
+      end
+
+      def pretty_type
+        "issue"
+      end
+
+      def fetch!
+        @data ||= HowIs.github.send(type).list(user: @user, repo: @repo)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "how_is/version"
+require "how_is/sources/github"
+require "how_is/sources/github_helpers"
+require "date"
+
+module HowIs::Sources
+  class Github
+    class Pulls < Issues
+      def type
+        "pulls"
+      end
+
+      def pretty_type
+        "pull request"
+      end
+    end
+  end
+end

data/lib/how_is/sources/github.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "how_is/sources"
+
+module HowIs
+  module Sources
+    class Github
+      # ...
+    end
+  end
+end