inq 26.0.0

data/lib/inq/cli.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "inq"
+require "inq/constants"
+require "okay/simple_opts"
+
+module Inq
+  ##
+  # Parses command-line arguments for inq.
+  class CLI
+    MissingArgument = Class.new(OptionParser::MissingArgument)
+
+    REPO_REGEXP = /.+\/.+/
+    DATE_REGEXP = /\d\d\d\d-\d\d-\d\d/
+
+    attr_reader :options, :help_text
+
+    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 Inq's 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
+
+    # 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: Inq::DEFAULT_REPORT_FILE,
+      }
+
+      opts = Okay::SimpleOpts.new(defaults: defaults)
+
+      opts.banner = <<~EOF
+        Usage: inq --repository REPOSITORY --date REPORT_DATE [--output REPORT_FILE]
+               inq --config CONFIG_FILE --date REPORT_DATE
+      EOF
+
+      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 this first: https://inqrb.com/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 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 [String] A comma-separated list of supported formats.
+    def formats
+      Inq.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 = Inq.supported_formats.map { |x| Regexp.escape(x) }
+
+      /.+\.(#{regexp_parts.join("|")})/
+    end
+  end
+end

data/lib/inq/config.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "inq/text"
+
+module Inq
+  HOME_CONFIG = File.join(Dir.home, ".config", "inq", "config.yml")
+
+  # Usage:
+  #     Inq::Config
+  #       .load_site_configs("/path/to/config1.yml", "/path/to/config2.yml")
+  #       .load_file("./repo-config.yml")
+  # Or:
+  #     Inq::Config
+  #       .load_defaults
+  #       .load_file("./repo-config.yml")
+  # Or:
+  #     Inq::Config
+  #       .load_defaults
+  #       .load({"repository" => "how-is/example-repository"})
+  class Config < Hash
+    attr_reader :site_configs
+
+    # If the INQ_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["INQ_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:
+    # - INQ_GITHUB_TOKEN: a GitHub authentication token.
+    # - INQ_GITHUB_USERNAME: the GitHub username corresponding to the token.
+    #
+    # @return [Config] The resulting configuration.
+    def load_env
+      Inq::Text.puts "Using configuration from environment variables."
+
+      gh_token = ENV["INQ_GITHUB_TOKEN"] || ENV["HOWIS_GITHUB_TOKEN"]
+      gh_username = ENV["INQ_GITHUB_USERNAME"] || ENV["HOWIS_GITHUB_USERNAME"]
+
+      raise "INQ_GITHUB_TOKEN environment variable is not set" \
+        unless gh_token
+      raise "INQ_GITHUB_USERNAME environment variable is not set" \
+        unless gh_username
+
+      load({
+        "sources/github" => {
+          "username" => gh_username,
+          "token" => gh_token,
+        },
+      })
+    end
+  end
+end

data/lib/inq/constants.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Inq
+  # 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 = "inq/#{Inq::VERSION} (https://github.com/duckinator/inq)"
+end

data/lib/inq/date_time_helpers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "inq/version"
+require "date"
+
+module Inq
+  ##
+  # 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/inq/exe.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "inq"
+require "inq/cli"
+require "inq/config"
+require "inq/text"
+
+module Inq
+  ##
+  # A module which implements the entire command-line interface for Inq.
+  module Exe
+    def self.run(argv)
+      cli = parse_args(argv)
+      options = cli.options
+
+      abort cli.help_text if options[:help]
+      abort Inq::VERSION_STRING if options[:version]
+
+      execute(options)
+    end
+
+    def self.parse_args(argv)
+      Inq::CLI.parse(argv)
+    rescue OptionParser::ParseError => e
+      abort "inq: error: #{e.message}"
+    end
+    private_class_method :parse_args
+
+    def self.load_config(options)
+      config = Inq::Config.new
+
+      config.load_defaults unless options[:no_user_config]
+      config.load_env if options[:env_config]
+
+      if options[:config]
+        config.load_files(options[:config])
+      else
+        config.load(Inq.default_config(options[:repository]))
+      end
+
+      config
+    end
+    private_class_method :load_config
+
+    def self.save_reports(reports)
+      files = reports.save_all
+      Inq::Text.puts "Saved reports to:"
+      files.each { |file| Inq::Text.puts "- #{file}" }
+    end
+    private_class_method :save_reports
+
+    def self.execute(options)
+      date = options[:date]
+      config = load_config(options)
+      reports = Inq.from_config(config, date)
+      save_reports(reports)
+    rescue => e
+      raise if options[:verbose]
+
+      warn "inq: error: #{e.message} (Pass --verbose for more details.)"
+      warn "  at: #{e.backtrace_locations.first}"
+      exit 1
+    end
+    private_class_method :execute
+  end
+end

data/lib/inq/frontmatter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "inq/version"
+require "okay/warning_helpers"
+
+module Inq
+  ##
+  # 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?
+
+      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'}
+    # @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
+  end
+end

data/lib/inq/report.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "inq/frontmatter"
+require "inq/cacheable"
+require "inq/sources/github/contributions"
+require "inq/sources/github/issues"
+require "inq/sources/github/pulls"
+require "inq/sources/ci/travis"
+require "inq/sources/ci/appveyor"
+require "inq/template"
+require "json"
+
+module Inq
+  ##
+  # Class for generating a report.
+  class Report
+    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.
+      #
+      #       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.)
+      end_dt = DateTime.strptime(end_date, "%Y-%m-%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")
+    end
+
+    def cache
+      @cache ||= Cacheable.new(@config, @start_date, @end_date)
+    end
+
+    def contributions
+      @gh_contributions ||= Sources::Github::Contributions.new(@config, @start_date, @end_date, cache)
+    end
+
+    def issues
+      @gh_issues ||= Sources::Github::Issues.new(@config, @start_date, @end_date, cache)
+    end
+
+    def pulls
+      @gh_pulls ||= Sources::Github::Pulls.new(@config, @start_date, @end_date, cache)
+    end
+
+    def travis
+      @travis ||= Sources::CI::Travis.new(@config, @start_date, @end_date, cache)
+    end
+
+    def appveyor
+      @appveyor ||= Sources::CI::Appveyor.new(@config, @start_date, @end_date, cache)
+    end
+
+    def to_h(frontmatter_data = nil)
+      @report_hash ||= report_hash
+      frontmatter = Frontmatter.generate(frontmatter_data, @report_hash)
+
+      @report_hash.merge(frontmatter: frontmatter)
+    end
+
+    def to_html_partial(frontmatter = nil)
+      Inq::Template.apply("report_partial.html", to_h(frontmatter))
+    end
+
+    def to_html(frontmatter = nil)
+      template_data = to_h(frontmatter).merge({report: to_html_partial})
+      Inq::Template.apply("report.html", template_data)
+    end
+
+    def to_json(frontmatter = nil)
+      frontmatter.to_s + JSON.pretty_generate(to_h)
+    end
+
+    def save_as(filename)
+      File.write(filename, to_format_for(filename))
+    end
+
+    def to_format_for(filename)
+      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