how_is 24.0.0 → 25.0.0

data/lib/how_is/config.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "how_is/text"
+
+module HowIs
+  HOME_CONFIG = File.join(Dir.home, ".config", "how_is", "config.yml")
+
+  # Usage:
+  #     HowIs::Config
+  #       .load_site_configs("/path/to/config1.yml", "/path/to/config2.yml")
+  #       .load_file("./repo-config.yml")
+  # Or:
+  #     HowIs::Config
+  #       .load_defaults
+  #       .load_file("./repo-config.yml")
+  # Or:
+  #     HowIs::Config
+  #       .load_defaults
+  #       .load({"repository" => "how-is/example-repository"})
+  class Config < Hash
+    attr_reader :site_configs
+
+    # If the +HOWIS_USE_ENV+ environment variable is set, load config from
+    # the environment.
+    #
+    # Otherwise, load the the default config file.
+    #
+    # @return [Hash] A Hash representation of the config.
+    def load_defaults
+      if ENV["HOWIS_USE_ENV"] == "true"
+        load_env
+      else
+        load_site_configs(HOME_CONFIG)
+      end
+    end
+
+    def initialize
+      super()
+      @site_configs = []
+    end
+
+    # Load the config files as specified via +files+.
+    #
+    # @param files [Array<String>] The path(s) for config files.
+    # @return [Config] The config hash. (+self+)
+    def load_site_configs(*files)
+      # Allows both:
+      #   load_site_configs('foo', 'bar')
+      #   load_site_configs(['foo', bar'])
+      # but not:
+      #   load_site_configs(['foo'], 'bar')
+      files = files[0] if files.length == 1 && files[0].is_a?(Array)
+
+      load_files(*files)
+    end
+
+    # TODO: See if this can be consolidated with load_site_configs.
+    def load_files(*file_paths)
+      files = (site_configs + file_paths).map { |f| Pathname.new(f) }
+
+      # Keep only files that exist.
+      files.select!(&:file?)
+
+      # Load the YAML files into Hashes.
+      configs = files.map { |file| YAML.safe_load(file.read) }
+
+      # Apply configs.
+      load(*configs)
+    end
+
+    # Take a collection of config hashes and cascade them, meaning values
+    # in later ones override values in earlier ones.
+    #
+    # E.g., this results in +{'a'=>'x', 'c'=>'d'}+:
+    #     load({'a'=>'b'}, {'c'=>'d'}, {'a'=>'x'})
+    #
+    # And this results in +{'a'=>['b', 'c']}+:
+    #     load({'a'=>['b']}, {'a'=>['c']})
+    #
+    # @param [Array<Hash>] The configuration hashes.
+    # @return [Config] The final configuration value.
+    def load(*configs)
+      configs.each do |config|
+        config.each do |k, v|
+          if self[k] && self[k].is_a?(Array)
+            self[k] += v
+          else
+            self[k] = v
+          end
+        end
+      end
+
+      self
+    end
+
+    # Load config info from environment variables.
+    #
+    # Supported environment variables:
+    # - HOWIS_GITHUB_TOKEN: a GitHub authentication token.
+    # - HOWIS_GITHUB_USERNAME: the GitHub username corresponding to the token.
+    #
+    # @return [Config] The resulting configuration.
+    def load_env
+      HowIs::Text.puts "Using configuration from environment variables."
+
+      gh_token = ENV["HOWIS_GITHUB_TOKEN"]
+      gh_username = ENV["HOWIS_GITHUB_USERNAME"]
+
+      raise "HOWIS_GITHUB_TOKEN environment variable is not set" \
+        unless gh_token
+      raise "HOWIS_GITHUB_USERNAME environment variable is not set" \
+        unless gh_username
+
+      load({
+        "sources/github" => {
+          "username" => gh_username,
+          "token" => gh_token,
+        },
+      })
+    end
+  end
+end

data/lib/how_is/constants.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module HowIs
+  # The file name used for a report if one isn't specified.
+  DEFAULT_REPORT_FILE = "report.html"
+
+  # Used by things making HTTP requests.
+  USER_AGENT = "how_is/#{HowIs::VERSION} (https://github.com/how-is/how_is/)"
+end

data/lib/how_is/date_time_helpers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "how_is/version"
+require "date"
+
+module HowIs
+  ##
+  # Various helper functions for working with DateTime objects.
+  module DateTimeHelpers
+    # Check if +left+ is less than or equal to +right+, where both are string
+    # representations of a date.
+    #
+    # @param left [String] A string representation of a date.
+    # @param right [String] A string representation of a date.
+    # @return [Boolean] True if +left+ is less-than-or-equal to +right+,
+    #   otherwise false.
+    def date_le(left, right)
+      left  = str_to_dt(left)
+      right = str_to_dt(right)
+
+      left <= right
+    end
+
+    # Check if +left+ is greater than or equal to +right+, where both are string
+    # representations of a date.
+    #
+    # @param left [String] A string representation of a date.
+    # @param right [String] A string representation of a date.
+    # @return [Boolean] True if +left+ is greater-than-or-equal to +right+,
+    #   otherwise false.
+    def date_ge(left, right)
+      left  = str_to_dt(left)
+      right = str_to_dt(right)
+
+      left >= right
+    end
+
+    private
+
+    # Converts a +String+ representation of a date to a +DateTime+.
+    #
+    # @param str [String] A date.
+    # @return [DateTime] A DateTime representation of +str+.
+    def str_to_dt(str)
+      DateTime.parse(str)
+    end
+  end
+end

data/lib/how_is/frontmatter.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 require "how_is/version"
+require "okay/warning_helpers"
 
 module HowIs
+  ##
+  # Module for generating YAML frontmatter, as used by Jekyll and other
+  # blog engines.
   module Frontmatter
+    extend Okay::WarningHelpers
+
     # 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"
+    #
+    # @param frontmatter [Hash] Frontmatter for the report.
+    # @param report_data [Hash] The report data itself.
+    # @return [String] A YAML dump of the generated frontmatter.
     def self.generate(frontmatter, report_data)
       return "" if frontmatter.nil?
 
@@ -29,18 +39,13 @@ module HowIs
     # @example
     #   convert_keys({'foo' => 'bar'}, :to_sym)
     #   # => {:foo => 'bar'}
+    # @param data [Hash] The input hash.
+    # @param method_name [Symbol] The method name used to convert keys.
+    #   (E.g. :to_s, :to_sym, etc.)
+    # @return [Hash] The converted result.
     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,15 +1,22 @@
 # frozen_string_literal: true
 
 require "how_is/frontmatter"
+require "how_is/cacheable"
 require "how_is/sources/github/contributions"
 require "how_is/sources/github/issues"
 require "how_is/sources/github/pulls"
-require "how_is/sources/travis"
+require "how_is/sources/ci/travis"
+require "how_is/sources/ci/appveyor"
+require "how_is/template"
+require "json"
 
 module HowIs
+  ##
+  # Class for generating a HowIs report.
   class Report
-    def initialize(repository, end_date)
-      @repository = repository
+    def initialize(config, end_date)
+      @config = config
+      @repository = config["repository"]
 
       # NOTE: Use DateTime because it defaults to UTC and that's less gross
       #       than trying to get Date to use UTC.
@@ -19,80 +26,50 @@ module HowIs
       #
       #       (I'm also guessing/hoping that GitHub's URLs use UTC.)
       end_dt = DateTime.strptime(end_date, "%Y-%m-%d")
-
-      d = end_dt.day
-      m = end_dt.month
-      y = end_dt.year
-      start_year = y
-      start_month = m - 1
-      if start_month <= 0
-        start_month = 12 - start_month
-        start_year -= 1
-      end
-      start_dt = DateTime.new(start_year, start_month, d)
+      start_dt = start_dt_from_end_dt(end_dt)
 
       @end_date = end_dt.strftime("%Y-%m-%d")
       @start_date = start_dt.strftime("%Y-%m-%d")
-
-      @gh_contributions = HowIs::Sources::Github::Contributions.new(repository, @start_date, @end_date)
-      @gh_issues        = HowIs::Sources::Github::Issues.new(repository, @start_date, @end_date)
-      @gh_pulls         = HowIs::Sources::Github::Pulls.new(repository, @start_date, @end_date)
-      @travis           = HowIs::Sources::Travis.new(repository, @start_date, @end_date)
     end
 
-    def to_h(frontmatter_data = nil)
-      @report_hash ||= {
-        title: "How is #{@repository}?",
-        repository: @repository,
-
-        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,
-
-        issues: @gh_issues.to_a,
-        pulls: @gh_issues.to_a,
-
-        average_issue_age: @gh_issues.average_age,
-        average_pull_age:  @gh_pulls.average_age,
-
-        oldest_issue_link: @gh_issues.oldest["url"],
-        oldest_issue_date: @gh_issues.oldest["createdAt"],
+    def cache
+      @cache ||= Cacheable.new(@config, @start_date, @end_date)
+    end
 
-        newest_issue_link: @gh_issues.newest["url"],
-        newest_issue_date: @gh_issues.newest["createdAt"],
+    def contributions
+      @gh_contributions ||= HowIs::Sources::Github::Contributions.new(@config, @start_date, @end_date, cache)
+    end
 
-        newest_pull_link: @gh_pulls.newest["url"],
-        newest_pull_date: @gh_pulls.newest["createdAt"],
+    def issues
+      @gh_issues ||= HowIs::Sources::Github::Issues.new(@config, @start_date, @end_date, cache)
+    end
 
-        oldest_pull_link: @gh_pulls.oldest["url"],
-        oldest_pull_date: @gh_pulls.oldest["createdAt"],
+    def pulls
+      @gh_pulls ||= HowIs::Sources::Github::Pulls.new(@config, @start_date, @end_date, cache)
+    end
 
-        travis_builds: @travis.builds.to_h,
+    def travis
+      @travis ||= HowIs::Sources::CI::Travis.new(@config, @start_date, @end_date, cache)
+    end
 
-        date: @end_date,
-      }
+    def appveyor
+      @appveyor ||= HowIs::Sources::CI::Appveyor.new(@config, @start_date, @end_date, cache)
+    end
 
-      frontmatter =
-        if frontmatter_data
-          HowIs::Frontmatter.generate(frontmatter_data, @report_hash)
-        else
-          ""
-        end
+    def to_h(frontmatter_data = nil)
+      @report_hash ||= report_hash
+      frontmatter = HowIs::Frontmatter.generate(frontmatter_data, @report_hash)
 
       @report_hash.merge(frontmatter: frontmatter)
     end
 
     def to_html_partial(frontmatter = nil)
-      template_data = to_h(frontmatter)
-
-      Kernel.format(HowIs.template("report_partial.html_template"), template_data)
+      HowIs::Template.apply("report_partial.html", to_h(frontmatter))
     end
 
     def to_html(frontmatter = nil)
       template_data = to_h(frontmatter).merge({report: to_html_partial})
-
-      Kernel.format(HowIs.template("report.html_template"), template_data)
+      HowIs::Template.apply("report.html", template_data)
     end
 
     def to_json(frontmatter = nil)
@@ -104,9 +81,60 @@ module HowIs
     end
 
     def to_format_for(filename)
-      format = filename.split(".").last
+      format = File.extname(filename)[1..-1]
       send("to_#{format}")
     end
     private :to_format_for
+
+    def start_dt_from_end_dt(end_dt)
+      d = end_dt.day
+      m = end_dt.month
+      y = end_dt.year
+      start_year = y
+      start_month = m - 1
+      if start_month <= 0
+        start_month = 12 - start_month
+        start_year -= 1
+      end
+
+      DateTime.new(start_year, start_month, d)
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def report_hash
+      {
+        title: "How is #{@repository}?",
+        repository: @repository,
+
+        contributions_summary: contributions.to_html,
+        new_contributors: contributions.new_contributors_html,
+        issues_summary: issues.to_html,
+        pulls_summary: pulls.to_html,
+
+        issues: issues.to_a,
+        pulls: issues.to_a,
+
+        average_issue_age: issues.average_age,
+        average_pull_age:  pulls.average_age,
+
+        oldest_issue_link: issues.oldest["url"],
+        oldest_issue_date: issues.oldest["createdAt"],
+
+        newest_issue_link: issues.newest["url"],
+        newest_issue_date: issues.newest["createdAt"],
+
+        newest_pull_link: pulls.newest["url"],
+        newest_pull_date: pulls.newest["createdAt"],
+
+        oldest_pull_link: pulls.oldest["url"],
+        oldest_pull_date: pulls.oldest["createdAt"],
+
+        travis_builds: travis.builds,
+        appveyor_builds: appveyor.builds,
+
+        date: @end_date,
+      }
+    end
+    # rubocop:enable Metrics/AbcSize
   end
 end

data/lib/how_is/report_collection.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "how_is/report"
+require "okay/warning_helpers"
+
+module HowIs
+  ##
+  # A class representing a collection of Reports.
+  class ReportCollection
+    include Okay::WarningHelpers
+
+    def initialize(config, date)
+      @config = config
+
+      # If the config is in the old format, convert it to the new one.
+      unless @config["repositories"]
+        @config["repositories"] = [{
+          "repository" => @config.delete("repository"),
+          "reports" => @config.delete("reports"),
+        }]
+      end
+
+      @date = date
+      @reports = config["repositories"].map(&method(:fetch_report)).to_h
+    end
+
+    # Generates the metadata for the collection of Reports.
+    def metadata(repository)
+      end_date = DateTime.strptime(@date, "%Y-%m-%d")
+      friendly_end_date = end_date.strftime("%B %d, %y")
+
+      {
+        sanitized_repository: repository.tr("/", "-"),
+        repository: repository,
+        date: end_date,
+        friendly_date: friendly_end_date,
+      }
+    end
+    private :metadata
+
+    def config_for(repo)
+      defaults = @config.fetch("default_reports", {})
+      config = @config.dup
+      repos = config.delete("repositories")
+
+      # Find the _last_ one that matches, to allow overriding.
+      repo_config = repos.reverse.find { |conf| conf["repository"] == repo }
+
+      # Use values from default_reports, unless overridden.
+      config["repository"] = repo
+      config["reports"] = defaults.merge(repo_config.fetch("reports", {}))
+      config
+    end
+    private :config_for
+
+    def fetch_report(repo_config)
+      repo = repo_config["repository"]
+      report = Report.new(config_for(repo), @date)
+      [repo, report]
+    end
+    private :fetch_report
+
+    # Converts a ReportCollection to a Hash.
+    #
+    # Also good for giving programmers nightmares, I suspect.
+    def to_h
+      results = {}
+      defaults = @config["default_reports"] || {}
+
+      @config["repositories"].map { |repo_config|
+        repo = repo_config["repository"]
+        config = config_for(repo)
+
+        config["reports"].map { |format, report_config|
+          # Sometimes report_data has unused keys, which generates a warning, but
+          # we're okay with it, so we wrap it with silence_warnings {}.
+          filename = silence_warnings {
+            tmp_filename = report_config["filename"] || defaults[format]["filename"]
+            tmp_filename % metadata(repo)
+          }
+
+          directory = report_config["directory"] || defaults[format]["directory"]
+          file = File.join(directory, filename)
+
+          # Export +report+ to the specified +format+ with the specified
+          # +frontmatter+.
+          frontmatter = report_config["frontmatter"] || {}
+          if defaults.has_key?(format) && defaults[format].has_key?("frontmatter")
+            frontmatter = defaults[format]["frontmatter"].merge(frontmatter)
+          end
+          frontmatter = nil if frontmatter == {}
+
+          export = @reports[repo].send("to_#{format}", frontmatter)
+
+          results[file] = export
+        }
+      }
+      results
+    end
+
+    # Save all of the reports to the corresponding files.
+    #
+    # @return [Array<String>] An array of file paths.
+    def save_all
+      reports = to_h
+      reports.each do |file, report|
+        File.write(file, report)
+      end
+
+      reports.keys
+    end
+  end
+end

data/lib/how_is/sources/ci/appveyor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "okay/default"
+require "okay/http"
+require "how_is/constants"
+require "how_is/sources"
+require "how_is/sources/github/contributions"
+require "how_is/text"
+
+module HowIs
+  module Sources
+    module CI
+      # Fetches metadata about CI builds from appveyor.com.
+      class Appveyor
+        # @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"]
+          @start_date = DateTime.parse(start_date)
+          @end_date = DateTime.parse(end_date)
+          @default_branch = Okay.default
+        end
+
+        # @return [String] The default branch name.
+        def default_branch
+          return @default_branch unless @default_branch.nil?
+
+          contributions =
+            HowIs::Sources::GitHub::Contributions.new(@config, nil, nil)
+
+          @default_branch = contributions.default_branch
+        end
+
+        # Fetches builds for the default branch.
+        #
+        # @return [Hash] Builds for the default branch.
+        def builds
+          @builds ||=
+            fetch_builds["builds"] \
+              .map(&method(:normalize_build)) \
+              .select(&method(:in_date_range?))
+        rescue Net::HTTPServerException
+          # It's not elegant, but it works™.
+          []
+        end
+
+        private
+
+        def in_date_range?(build)
+          build["started_at"] >= @start_date &&
+            build["started_at"] <= @end_date
+        end
+
+        def normalize_build(build)
+          build["started_at"] = DateTime.parse(build["created"])
+          build["html_url"] = "https://ci.appveyor.com/project/#{@repository}/build/#{build['buildNumber']}"
+          build
+        end
+
+        # Returns API result of /api/projects/:repository.
+        # FIXME: This doesn't limit results based on the date range.
+        #
+        # @return [Hash] API results.
+        def fetch_builds
+          @cache.cached("appveyor_builds") do
+            HowIs::Text.print "Fetching Appveyor build data."
+
+            ret = Okay::HTTP.get(
+              "https://ci.appveyor.com/api/projects/#{@repository}/history",
+              parameters: {"recordsNumber" => "100"},
+              headers: {
+                "Accept" => "application/json",
+                "User-Agent" => HowIs::USER_AGENT,
+              }
+            ).or_raise!.from_json
+
+            HowIs::Text.puts
+            ret
+          end
+        end
+      end
+    end
+  end
+end