how_is 24.0.0 → 25.0.0

data/fixtures/vcr_cassettes/how_is_contributions_new_contributors.yml

@@ -709,4 +709,73 @@ http_interactions:
       string: "[]"
     http_version: 
   recorded_at: Sat, 06 Jan 2018 20:10:44 GMT
-recorded_with: VCR 3.0.3
+- request:
+    method: get
+    uri: https://api.github.com/repos/how-is/example_repository/commits?since=2017-08-01&until=2017-09-01
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - application/vnd.github.v3+json,application/vnd.github.beta+json;q=0.5,application/json;q=0.1
+      Accept-Charset:
+      - utf-8
+      User-Agent:
+      - Github API Ruby Gem 0.18.2
+      Authorization:
+      - Basic ZHVja2luYXRvcjo5MTgyNzc3ZmYzYzAwNjc5NTE5M2E1NzBjZGFjMzI2YjY0NDU5ZGM5
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 404
+      message: Not Found
+    headers:
+      Server:
+      - GitHub.com
+      Date:
+      - Thu, 17 Jan 2019 23:31:08 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Status:
+      - 404 Not Found
+      X-Ratelimit-Limit:
+      - '5000'
+      X-Ratelimit-Remaining:
+      - '4998'
+      X-Ratelimit-Reset:
+      - '1547771467'
+      X-Oauth-Scopes:
+      - ''
+      X-Accepted-Oauth-Scopes:
+      - repo
+      X-Github-Media-Type:
+      - github.v3; format=json
+      Access-Control-Expose-Headers:
+      - ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining,
+        X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval,
+        X-GitHub-Media-Type
+      Access-Control-Allow-Origin:
+      - "*"
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubdomains; preload
+      X-Frame-Options:
+      - deny
+      X-Content-Type-Options:
+      - nosniff
+      X-Xss-Protection:
+      - 1; mode=block
+      Referrer-Policy:
+      - origin-when-cross-origin, strict-origin-when-cross-origin
+      Content-Security-Policy:
+      - default-src 'none'
+      X-Github-Request-Id:
+      - E2DD:74AE:2EA1532:5A89EC1:5C41103C
+    body:
+      encoding: ASCII-8BIT
+      string: '{"message":"Not Found","documentation_url":"https://developer.github.com/v3/repos/commits/#list-commits-on-a-repository"}'
+    http_version: 
+  recorded_at: Thu, 17 Jan 2019 23:31:08 GMT
+recorded_with: VCR 4.0.0

data/fixtures/vcr_cassettes/how_is_contributions_summary.yml

@@ -480,4 +480,73 @@ http_interactions:
         commit","tree":{"sha":"8286e548e330cfe01efcf7189f4df1fa53e777a7","url":"https://api.github.com/repos/how-is/example-repository/git/trees/8286e548e330cfe01efcf7189f4df1fa53e777a7"},"url":"https://api.github.com/repos/how-is/example-repository/git/commits/3794aa1c4b76623748faf280abe5760b76823162","comment_count":0,"verification":{"verified":false,"reason":"unsigned","signature":null,"payload":null}},"url":"https://api.github.com/repos/how-is/example-repository/commits/3794aa1c4b76623748faf280abe5760b76823162","html_url":"https://github.com/how-is/example-repository/commit/3794aa1c4b76623748faf280abe5760b76823162","comments_url":"https://api.github.com/repos/how-is/example-repository/commits/3794aa1c4b76623748faf280abe5760b76823162/comments","author":null,"committer":null,"parents":[{"sha":"9e29405efa433529b86722542b8fb4b34dfd9edd","url":"https://api.github.com/repos/how-is/example-repository/commits/9e29405efa433529b86722542b8fb4b34dfd9edd","html_url":"https://github.com/how-is/example-repository/commit/9e29405efa433529b86722542b8fb4b34dfd9edd"}]}]'
     http_version: 
   recorded_at: Sat, 06 Jan 2018 20:10:45 GMT
-recorded_with: VCR 3.0.3
+- request:
+    method: get
+    uri: https://api.github.com/repos/how-is/example_repository
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - application/vnd.github.v3+json,application/vnd.github.beta+json;q=0.5,application/json;q=0.1
+      Accept-Charset:
+      - utf-8
+      User-Agent:
+      - Github API Ruby Gem 0.18.2
+      Authorization:
+      - Basic ZHVja2luYXRvcjo5MTgyNzc3ZmYzYzAwNjc5NTE5M2E1NzBjZGFjMzI2YjY0NDU5ZGM5
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 404
+      message: Not Found
+    headers:
+      Server:
+      - GitHub.com
+      Date:
+      - Thu, 17 Jan 2019 23:31:09 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Status:
+      - 404 Not Found
+      X-Ratelimit-Limit:
+      - '5000'
+      X-Ratelimit-Remaining:
+      - '4990'
+      X-Ratelimit-Reset:
+      - '1547771467'
+      X-Oauth-Scopes:
+      - ''
+      X-Accepted-Oauth-Scopes:
+      - repo
+      X-Github-Media-Type:
+      - github.v3; format=json
+      Access-Control-Expose-Headers:
+      - ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining,
+        X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval,
+        X-GitHub-Media-Type
+      Access-Control-Allow-Origin:
+      - "*"
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubdomains; preload
+      X-Frame-Options:
+      - deny
+      X-Content-Type-Options:
+      - nosniff
+      X-Xss-Protection:
+      - 1; mode=block
+      Referrer-Policy:
+      - origin-when-cross-origin, strict-origin-when-cross-origin
+      Content-Security-Policy:
+      - default-src 'none'
+      X-Github-Request-Id:
+      - A3D7:74B0:25D2A89:4E64487:5C41103D
+    body:
+      encoding: ASCII-8BIT
+      string: '{"message":"Not Found","documentation_url":"https://developer.github.com/v3/repos/#get"}'
+    http_version: 
+  recorded_at: Thu, 17 Jan 2019 23:31:09 GMT
+recorded_with: VCR 4.0.0

data/fixtures/vcr_cassettes/how_is_contributions_summary_2.yml

@@ -480,4 +480,73 @@ http_interactions:
         commit","tree":{"sha":"8286e548e330cfe01efcf7189f4df1fa53e777a7","url":"https://api.github.com/repos/how-is/example-repository/git/trees/8286e548e330cfe01efcf7189f4df1fa53e777a7"},"url":"https://api.github.com/repos/how-is/example-repository/git/commits/3794aa1c4b76623748faf280abe5760b76823162","comment_count":0,"verification":{"verified":false,"reason":"unsigned","signature":null,"payload":null}},"url":"https://api.github.com/repos/how-is/example-repository/commits/3794aa1c4b76623748faf280abe5760b76823162","html_url":"https://github.com/how-is/example-repository/commit/3794aa1c4b76623748faf280abe5760b76823162","comments_url":"https://api.github.com/repos/how-is/example-repository/commits/3794aa1c4b76623748faf280abe5760b76823162/comments","author":null,"committer":null,"parents":[{"sha":"9e29405efa433529b86722542b8fb4b34dfd9edd","url":"https://api.github.com/repos/how-is/example-repository/commits/9e29405efa433529b86722542b8fb4b34dfd9edd","html_url":"https://github.com/how-is/example-repository/commit/9e29405efa433529b86722542b8fb4b34dfd9edd"}]}]'
     http_version: 
   recorded_at: Sat, 06 Jan 2018 20:10:45 GMT
-recorded_with: VCR 3.0.3
+- request:
+    method: get
+    uri: https://api.github.com/repos/how-is/example_repository
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - application/vnd.github.v3+json,application/vnd.github.beta+json;q=0.5,application/json;q=0.1
+      Accept-Charset:
+      - utf-8
+      User-Agent:
+      - Github API Ruby Gem 0.18.2
+      Authorization:
+      - Basic ZHVja2luYXRvcjo5MTgyNzc3ZmYzYzAwNjc5NTE5M2E1NzBjZGFjMzI2YjY0NDU5ZGM5
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 404
+      message: Not Found
+    headers:
+      Server:
+      - GitHub.com
+      Date:
+      - Thu, 17 Jan 2019 23:31:09 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Status:
+      - 404 Not Found
+      X-Ratelimit-Limit:
+      - '5000'
+      X-Ratelimit-Remaining:
+      - '4989'
+      X-Ratelimit-Reset:
+      - '1547771467'
+      X-Oauth-Scopes:
+      - ''
+      X-Accepted-Oauth-Scopes:
+      - repo
+      X-Github-Media-Type:
+      - github.v3; format=json
+      Access-Control-Expose-Headers:
+      - ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining,
+        X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval,
+        X-GitHub-Media-Type
+      Access-Control-Allow-Origin:
+      - "*"
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubdomains; preload
+      X-Frame-Options:
+      - deny
+      X-Content-Type-Options:
+      - nosniff
+      X-Xss-Protection:
+      - 1; mode=block
+      Referrer-Policy:
+      - origin-when-cross-origin, strict-origin-when-cross-origin
+      Content-Security-Policy:
+      - default-src 'none'
+      X-Github-Request-Id:
+      - B1CE:74B1:1A6A899:3C03775:5C41103D
+    body:
+      encoding: ASCII-8BIT
+      string: '{"message":"Not Found","documentation_url":"https://developer.github.com/v3/repos/#get"}'
+    http_version: 
+  recorded_at: Thu, 17 Jan 2019 23:31:09 GMT
+recorded_with: VCR 4.0.0

data/how_is.gemspec

@@ -19,20 +19,26 @@ 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.18.1"
-  spec.add_runtime_dependency "contracts", "~> 0.16.0"
+  # how_is only supports Ruby versions under "normal maintenance".
+  # This number should be updated when a Ruby version goes into security
+  # maintenance.
+  #
+  # Ruby maintenance info: https://www.ruby-lang.org/en/downloads/branches/
+  #
+  # NOTE: Update Gemfile when this is updated!
+  spec.required_ruby_version = "~> 2.4"
 
-  spec.add_runtime_dependency "okay", "~> 7.0.0"
+  spec.add_runtime_dependency "github_api", "~> 0.18.1"
+  spec.add_runtime_dependency "okay", "~> 11.0"
 
   spec.add_runtime_dependency "json"
 
-  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 12.3"
-  spec.add_development_dependency "rspec", "~> 3.7"
+  spec.add_development_dependency "rspec", "~> 3.8"
   spec.add_development_dependency "timecop", "~> 0.9.1"
   spec.add_development_dependency "vcr", "~> 4.0"
   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/cacheable.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tmpdir"
+
+module HowIs
+  # Class for use in caching expensive operations
+  class Cacheable
+    def initialize(config, start_date, end_date, tmpdir = Dir.mktmpdir)
+      @config = config
+      @start_date = start_date
+      @end_date = end_date
+      @tmpdir = tmpdir
+    end
+
+    def cached(key, extra_digest = nil)
+      cache = @config["cache"]
+      return yield if cache.nil?
+
+      hash_key = []
+      hash_key << Digest::SHA1.hexdigest(extra_digest) if extra_digest
+      hash_key << Digest::SHA1.hexdigest(@config.to_json)
+      cache_key = File.join(@start_date, @end_date, key, hash_key.join("-"))
+
+      case cache["type"]
+      when "marshal"
+        MarshalCache.cached(cache_key, @tmpdir) { yield }
+      when "self"
+        # Can provide your own cache in HowIs.new
+        # e.g.
+        # cache_mechanism = ->(cache_key, config, block) do
+        #   if cached?
+        #     cached_value
+        #   else
+        #     block.call
+        #   end
+        # end
+        # HowIs.new("owner/repo", date, cache_mechanism)
+        cache["cache_mechanism"].call(cache_key, @config, ->() { yield })
+      end
+    end
+
+    # This is only okay on a local system
+    module MarshalCache
+      class << self
+        # rubocop:disable Security/MarshalLoad
+        def cached(key, tmpdir)
+          require "fileutils"
+
+          path = File.join(tmpdir, "how_is", key)
+          FileUtils.mkdir_p(File.dirname(path))
+
+          ret = nil
+          if File.exist?(path)
+            File.open(path, "rb") do |f|
+              ret = Marshal.load(f)
+            end
+            ret
+          else
+            ret = yield
+            File.open(path, "wb") do |file|
+              Marshal.dump(ret, file)
+            end
+          end
+          ret
+        end
+        # rubocop:enable Security/MarshalLoad
+      end
+    end
+  end
+end

data/lib/how_is/cli.rb

@@ -1,138 +1,135 @@
-# NOPE THIS IS BROKEN // frozen_string_literal: // true
+# frozen_string_literal: true
 
 require "how_is"
-require "optparse"
+require "how_is/constants"
+require "okay/simple_opts"
 
-module HowIs::CLI
-  # Parent class of all exceptions raised in HowIs::CLI.
-  class OptionsError < StandardError
-  end
+module HowIs
+  ##
+  # Parses command-line arguments for how_is.
+  class CLI
+    MissingArgument = Class.new(OptionParser::MissingArgument)
 
-  # Raised when the specified output file can't be used.
-  class InvalidOutputFileError < OptionsError
-  end
+    REPO_REGEXP = /.+\/.+/
+    DATE_REGEXP = /\d\d\d\d-\d\d-\d\d/
 
-  # Raised when the specified input file doesn't contain
-  # a valid JSON report.
-  class InvalidInputFileError < OptionsError
-  end
+    attr_reader :options, :help_text
 
-  # Raised when no repository is specified, but one is required.
-  # (It's _not_ required, e.g., when +--config+ is passed.)
-  class HowIsArgumentError < OptionsError
-  end
+    def self.parse(*args)
+      new.parse(*args)
+    end
+
+    def initialize
+      @options = nil
+      @help_text = nil
+    end
+
+    # Parses an Array of command-line arguments into an equivalent Hash.
+    #
+    # The results of this can be used to control the behavior of the rest
+    # of the library.
+    #
+    # @params argv [Array] An array of command-line arguments, e.g. +ARGV+.
+    # @return [Hash] A Hash containing data used to control HowIs behavior.
+    def parse(argv)
+      parser, options = parse_main(argv)
+
+      # Options that are mutually-exclusive with everything else.
+      options = {:help    => true} if options[:help]
+      options = {:version => true} if options[:version]
+
+      validate_options!(options)
+
+      @options = options
+      @help_text = parser.to_s
+
+      self
+    end
+
+    private
+
+    # parse_main() is as short as can be managed. It's fine as-is.
+    # rubocop:disable Metrics/MethodLength
 
-  # Parses +argv+ to generate an options Hash to control the behavior of
-  # the library.
-  def self.parse(argv)
-    options = {}
-    opts_ = nil
-
-    opt_parser = OptionParser.new do |opts|
-      opts_ = opts
-      # General usage information.
-      opts.banner =
-        <<-EOF.gsub(/ *\| ?/, '')
-        | Usage: how_is REPOSITORY REPORT_DATE [--output REPORT_FILE]
-        |        how_is REPORT_DATE --config CONFIG_FILE
-        |
-        | Where:
-        |   REPOSITORY is <GitHub username or org>/<repository name>.
-        | and
-        |   REPORT_DATE is the last day the report covers, in the format YYYY-mm-dd.
-        |
-        | E.g., if you wanted to check https://github.com/how-is/how_is for
-        | November 01 2016 through December 01 2016, you'd run:
-        |   how_is how-is/how_is 2016-12-01
-        |
+    # This does a significant chunk of the work for parse().
+    #
+    # @return [Array] An array containing the +OptionParser+ and the result
+    #   of running it.
+    def parse_main(argv)
+      defaults = {
+        report: HowIs::DEFAULT_REPORT_FILE,
+      }
+
+      opts = Okay::SimpleOpts.new(defaults: defaults)
+
+      opts.banner = <<~EOF
+        Usage: how_is --repository REPOSITORY --date REPORT_DATE [--output REPORT_FILE]
+               how_is --config CONFIG_FILE --date REPORT_DATE
       EOF
 
-      opts.separator ""
-      opts.separator "Options:"
-
-      # The extra spaces make this a lot easier to comprehend, so we don't want
-      # RuboCop to complain about them.
-      #
-      # Same for line length.
-      #
-      # rubocop:disable Style/SpaceBeforeFirstArg
-      # rubocop:disable Metrics/LineLength
-
-      opts.on("--config CONFIG_FILE",
-              "YAML config file, used to generate a group of reports") do |filename|
-        options[:config] = filename
-      end
-
-      opts.on("--output REPORT_FILE",
-              "Output file for the report (valid extensions: #{HowIs.supported_formats.join(', ')}; default: #{HowIs::DEFAULT_REPORT_FILE})") do |filename|
-        options[:report] = filename
-      end
-
-      opts.on("-v", "--version",
-              "Prints version information") do
-        options[:version] = true
-      end
-
-      opts.on("-h", "--help",
-              "Print help text") do
-        options[:help] = true
-      end
+      opts.separator "\nOptions:"
+
+      opts.simple("--config CONFIG_FILE",
+                  "YAML config file for automated reports.",
+                  :config)
+
+      opts.simple("--no-user-config",
+                  "Don't load user configuration file.",
+                  :no_user_config)
+
+      opts.simple("--env-config",
+                  "Use environment variables for configuration.",
+                  "Read first: https://how-is.github.io/config",
+                  :env_login)
+
+      opts.simple("--repository USER/REPO", REPO_REGEXP,
+                  "Repository to generate a report for.",
+                  :repository)
+
+      opts.simple("--date YYYY-MM-DD", DATE_REGEXP, "Last date of the report.",
+                  :date)
+
+      opts.simple("--output REPORT_FILE", format_regexp,
+                  "Output file for the report.",
+                  "Supported file formats: #{formats}.",
+                  :report)
+
+      opts.simple("--verbose", "Print debug information.", :verbose)
+      opts.simple("-v", "--version", "Prints version information.", :version)
+      opts.simple("-h", "--help", "Print help text.", :help)
+
+      [opts, opts.parse(argv)]
     end
-    # rubocop:enable Style/SpaceBeforeFirstArg
-    # rubocop:enable Metrics/LineLength
-
-    # `.parse!` populates the `options` Hash that was
-    # created above, and the return value is any non-flag
-    # arguments.
-    arguments = opt_parser.parse!(argv)
-
-    # TODO: Should this raise an exception instead?
-    keep_only = lambda { |options_, key| options_.select { |k, v| k == key } }
-
-    if options[:help]
-      # If --help is passed, _only_ accept --help.
-      options = keep_only.call(options, :help)
-    elsif options[:version]
-      # If --version is passed, _only_ accept --version.
-      options = keep_only.call(options, :version)
-    elsif options[:config]
-      # If --config is passed, _only_ accept --config.
-      options = keep_only.call(options, :config)
-      if argv.length >= 1
-        options[:date] = argv.delete_at(0)
-      else
-        raise HowIsArgumentError, "Expected date."
-      end
-    else
-      # 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 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])
-        raise InvalidOutputFileError, "Invalid file: #{options[:report]}. Supported formats: #{HowIs.supported_formats.join(', ')}"
-      end
-
-      if argv.length >= 2
-        options[:repository] = argv.delete_at(0)
-        options[:date] = argv.delete_at(0)
-      else
-        raise HowIsArgumentError, "Expected both repository and date."
-      end
+
+    # rubocop:enable Metrics/MethodLength
+
+    # Given an +options+ Hash, determine if we got a valid combination of
+    # options.
+    #
+    # 1. Anything with `--help` and `--version` is always valid.
+    # 2. Otherwise, `--repository` or `--config` is required.
+    # 3. If `--repository` or `--config` is required, so is `--date`.
+    #
+    # @param options [Hash] The result of CLI#parse().
+    # @raise [MissingArgument] if we did not get a valid options Hash.
+    def validate_options!(options)
+      return if options[:help] || options[:version]
+      raise MissingArgument, "--date" unless options[:date]
+      raise MissingArgument, "--repository or --config" unless
+        options[:repository] || options[:config]
     end
 
-    # Return a Hash with:
-    #   +opts+: the original Slop::Options object.
-    #   +options+: the Hash of flags/values (e.g. +--foo bar+ becomes
-    #     +options[:foo]+ with the value of +"bar"+).
-    #   +arguments+: an Array of arguments that don't have a
-    #     corresponding flags.
-    {
-      opts: opts_,
-      options: options,
-      arguments: arguments,
-    }
+    # @return [String] A comma-separated list of supported formats.
+    def formats
+      HowIs.supported_formats.join(", ")
+    end
+
+    # @return [Regexp] a +Regexp+ object which matches any path ending
+    #   with an extension corresponding to a supported format.
+    def format_regexp
+      regexp_parts = HowIs.supported_formats.map { |x| Regexp.escape(x) }
+
+      /.+\.(#{regexp_parts.join("|")})/
+    end
   end
 end