how_is 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2a6fdbded1ff0bf48eba79e033d60b63fe5b3227
+  data.tar.gz: 3cce6191b1f525431233d27fc856f593d2e59b3f
+SHA512:
+  metadata.gz: 9c6e101d9dbf277c6df9f21b0c68457316bd346a2d97d93472a9f4661d44f06ae9987901368e5bb09b24f63d6e66e2ee71f5f91c5c8ff03b46d9d4696e993afd
+  data.tar.gz: 7f66062db788773e525b566acc9b8f38cbcb9c381176f8150059368601e04a10d096867e70e80457e571d9a4b4de678c9954dd55bad81e9406e30981677e342f

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+report.pdf
+report.json
+*.dat
+*.png

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.2
+  - jruby
+  - rbx-2
+before_install: gem install bundler -v 1.11.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at me@duckie.co. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in how_is.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ellen Marie Dash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+[![Stories in Ready](https://badge.waffle.io/duckinator/how_is.png?label=ready&title=Ready)](https://waffle.io/duckinator/how_is)
+# How is [your repo]?
+
+`how_is` is tool for generating summaries of the health of a codebase. It uses information available from issues and pull requests to provide an overview of a repository and highlight problem areas of the codebase.
+
+The summary includes:
+
+* repository name,
+* number of open issues,
+* number of open pull requests,
+* number of open issues associated with each label and with no label,
+* average issue age,
+* average pull request age,
+* date oldest issue was opened,
+* date oldest pull request was opened.
+
+## Installation
+
+    $ gem install how_is
+
+## Usage
+
+    $ how_is <orgname>/<reponame> [--report-file FILENAME]
+
+E.g.,
+
+    $ how_is rubygems/rubygems --report-file report.pdf
+
+The above command creates a PDF containing the summary at `./report.pdf`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. Run `bundle exec how_is` to use the gem in this directory, ignoring other installed copies of this gem.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/duckinator/how_is. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "how_is"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/data/issues.plg

@@ -0,0 +1,22 @@
+if (!exists("chartsize")) chartsize = '500,500'
+if (!exists("labelfont")) labelfont = 'Helvetica,12'
+if (!exists("chartfont")) chartfont = 'Helvetica,12'
+if (!exists("data")) data = 'issues-per-label.dat'
+if (!exists("pngfile")) data = 'issues-per-label.png'
+
+set terminal png size chartsize font chartfont
+
+set output pngfile
+
+unset key
+unset border
+set tics nomirror
+unset xtics
+
+set style fill solid 0.15 border
+
+plot data using 1:2 with boxes, data using 1:(0):3 with \
+      labels left \
+      rotate by 90 \
+      font labelfont \
+      offset 0,0.45

data/exe/how_is

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+require "how_is"
+require "optparse"
+
+options = {
+  repository: nil,
+  report_file:  "report.pdf",
+  from_file: nil,
+}
+
+opts = OptionParser.new do |opts|
+  opts.banner =
+    <<-EOF.gsub(/ *\| ?/, '')
+      | Usage: how_is REPOSITORY [--report REPORT_FILE]
+      |
+      | Where REPOSITORY is of the format <GitHub username or org>/<repository name>.
+      |
+      | E.g., if you wanted to check https://github.com/duckinator/how_is,
+      | you'd run `how_is duckinator/how_is`.
+      |
+    EOF
+
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-h", "--help", "Print this help") do
+    puts opts
+    exit 0
+  end
+
+  opts.on("--from JSON_REPORT_FILE", "import JSON_REPORT_FILE instead of fetching the data again") do |file|
+    options[:from_file] = file
+  end
+
+  opts.on("--report REPORT_FILE", "CSV file containing the report") do |file|
+    options[:report_file] = file
+  end
+end
+opts.parse!
+
+if ARGV.length >= 1
+  options[:repository] = ARGV.delete_at(0)
+else
+  abort "Error: No repository specified."
+end
+
+HowIs.generate_report(options)

data/how_is.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'how_is/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "how_is"
+  spec.version       = HowIs::VERSION
+  spec.authors       = ["Ellen Marie Dash"]
+  spec.email         = ["me@duckie.co"]
+
+  spec.summary       = %q{Quantify the health of a GitHub repository is.}
+  spec.homepage      = "https://github.com/duckinator/how_is"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "github_api", "~> 0.13.1"
+  spec.add_runtime_dependency "configru", "~> 3.6.0"
+  spec.add_runtime_dependency "contracts"
+  spec.add_runtime_dependency "prawn"
+
+  spec.add_runtime_dependency "mini_magick"
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/how_is/analyzer.rb

@@ -0,0 +1,142 @@
+require 'contracts'
+require 'ostruct'
+require 'date'
+require 'json'
+
+module HowIs
+  ##
+  # Represents a completed analysis of the repository being analyzed.
+  class Analysis < OpenStruct
+  end
+
+  class Analyzer
+    include Contracts::Core
+
+    class UnsupportedImportFormat < StandardError
+      def initialize(format)
+        super("Unsupported import format: #{format}")
+      end
+    end
+
+    Contract Fetcher::Results, C::KeywordArgs[analysis_class: C::Optional[Class]] => Analysis
+    def call(data, analysis_class: Analysis)
+      issues = data.issues
+      pulls = data.pulls
+
+      analysis_class.new(
+        repository: data.repository,
+
+        number_of_issues:  issues.length,
+        number_of_pulls:   pulls.length,
+
+        issues_with_label: num_with_label(issues),
+        issues_with_no_label: num_with_no_label(issues),
+
+        average_issue_age: average_age_for(issues),
+        average_pull_age:  average_age_for(pulls),
+
+        oldest_issue_date: oldest_date_for(issues),
+        oldest_pull_date:  oldest_date_for(pulls),
+      )
+    end
+
+    def from_file(file)
+      extension = file.split('.').last
+      raise UnsupportedImportFormat, extension unless extension == 'json'
+
+      hash = JSON.parse(open(file).read)
+      hash = hash.map do |k, v|
+        v = DateTime.parse(v) if k.end_with?('_date')
+
+        [k, v]
+      end.to_h
+
+      Analysis.new(hash)
+    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
+
+    def num_with_no_label(issues)
+      issues.select { |x| x['labels'].empty? }.length
+    end
+
+    def average_date_for(issues_or_pulls)
+      timestamps = issues_or_pulls.map { |iop| Time.parse(iop['created_at']).to_i }
+      average_timestamp = timestamps.reduce(:+) / issues_or_pulls.length
+
+      average_time = Time.at(average_timestamp)
+      Date.parse(average_time.to_s)
+    end
+
+    # Given an Array of issues or pulls, return the average age of them.
+    def average_age_for(issues_or_pulls)
+      ages = issues_or_pulls.map {|iop| time_ago_in_seconds(iop['created_at'])}
+      raw_average = ages.reduce(:+) / ages.length
+
+      seconds_in_a_year = 31_556_926
+      seconds_in_a_month = 2_629_743
+      seconds_in_a_week = 604_800
+      seconds_in_a_day = 86_400
+
+      years = raw_average / seconds_in_a_year
+      years_remainder = raw_average % seconds_in_a_year
+
+      months = years_remainder / seconds_in_a_month
+      months_remainder = years_remainder % seconds_in_a_month
+
+      weeks = months_remainder / seconds_in_a_week
+      weeks_remainder = months_remainder % seconds_in_a_week
+
+      days = weeks_remainder / seconds_in_a_day
+
+      values = [
+        [years, "year"],
+        [months, "month"],
+        [weeks, "week"],
+        [days, "day"],
+      ].reject {|(v, k)| v == 0}.map{ |(v,k)|
+        k = k + 's' if v != 1
+        [v, k]
+      }
+
+      most_significant = values[0, 2].map {|x| x.join(" ")}
+
+      if most_significant.length < 2
+        value = most_significant.first
+      else
+        value = most_significant.join(" and ")
+      end
+
+      "approximately #{value}"
+    end
+
+    # Given an Array of issues or pulls, return the creation date of the oldest.
+    def oldest_date_for(issues_or_pulls)
+      issues_or_pulls.map {|x| DateTime.parse(x['created_at']) }.sort.first
+    end
+
+  private
+    def time_ago_in_seconds(x)
+      DateTime.now.strftime("%s").to_i - DateTime.parse(x).strftime("%s").to_i
+    end
+  end
+end

data/lib/how_is/chart.rb

@@ -0,0 +1,83 @@
+class HowIs::Chart
+  # Generates the gnuplot script in data/issues.plg.
+  #
+  # Some configuration is available. Font locations are path to a TTF or other
+  # Gnuplot-readable font name.
+  #
+  # For example that could be '/Users/anne/Library/Fonts/InputMono-Medium.ttf'
+  # or just 'Helvetica'.
+  #
+  # @param font_location [String] Font for the chart
+  # @param font_size [Integer] Size of the chart text
+  # @param label_font_location [String] Font for labels
+  # @param label_font_size [Integer] Size of the label text
+  #
+  # @return void
+  def self.gnuplot(font_location: nil,
+                   font_size: 16,
+                   label_font_location: nil,
+                   label_font_size: 10,
+                   chartsize: '500,500',
+                   data_file:,
+                   png_file:)
+    default_font_location =
+      if Gem.win_platform?
+        'Arial'
+      else
+        'Helvetica'
+      end
+
+    font_location ||= default_font_location
+    label_font_location ||= font_location
+
+    cmd = %Q{
+      gnuplot -e "labelfont='#{label_font_location},#{label_font_size}'" \
+              -e "chartfont='#{font_location},#{font_size}'" \
+              -e "chartsize='#{chartsize}'" \
+              -e "data='#{data_file}'" \
+              -e "pngfile='#{png_file}'" \
+              -c data/issues.plg
+    }
+    puts cmd
+    IO.popen(cmd, 'w')
+  end
+
+  def self.rotate(offset, filename)
+    if Gem.win_platform?
+      rotate_with_dotnet(filename, offset)
+    else
+      rotate_with_minimagick(filename, offset)
+    end
+  end
+
+  def self.rotate_with_dotnet(filename, offset)
+    ps_rotate_flip = {
+      90  => 'Rotate90FlipNone',
+      180 => 'Rotate180FlipNone',
+      270 => 'Rotate270FlipNone',
+      -90 => 'Rotate270FlipNone'
+    }[offset]
+
+    command = %Q{
+      $path = "#{filename}"
+
+      [Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms");
+      $i = new-object System.Drawing.Bitmap $path
+
+      $i.RotateFlip("#{ps_rotate_flip}")
+
+      $i.Save($path,"png")
+
+      exit
+    }
+
+    IO.popen(["powershell", "-Command", command], 'w') { |io| }
+  end
+
+  def self.rotate_with_minimagick(filename, offset)
+    require 'mini_magick'
+    image = MiniMagick::Image.new(filename) { |b| b.rotate offset.to_s }
+    image.format 'png'
+    image.write filename
+  end
+end

data/lib/how_is/fetcher.rb

@@ -0,0 +1,44 @@
+require 'contracts'
+require 'github_api'
+
+##
+# Fetches data from GitHub.
+class HowIs::Fetcher
+  include Contracts::Core
+
+  ##
+  # Standardized representation for fetcher results.
+  #
+  # Implemented as a class instead of passing around a Hash so that it can
+  # be more easily referenced by Contracts.
+  class Results < Struct.new(:repository, :issues, :pulls)
+    include Contracts::Core
+
+    Contract String, C::ArrayOf[Hash], C::ArrayOf[Hash] => nil
+    def initialize(repository, issues, pulls)
+      super(repository, issues, pulls)
+    end
+
+    # Struct defines #to_h, but not #to_hash, so we alias them.
+    alias_method :to_hash, :to_h
+  end
+
+
+  Contract String, C::RespondTo[:issues, :pulls] => Results
+  def call(repository,
+        github = Github.new(auto_pagination: true))
+    user, repo = repository.split('/', 2)
+    issues  = github.issues.list user: user, repo: repo
+    pulls   = github.pulls.list  user: user, repo: repo
+
+    Results.new(
+      repository,
+      obj_to_array_of_hashes(issues),
+      obj_to_array_of_hashes(pulls)
+    )
+  end
+
+  private def obj_to_array_of_hashes(object)
+    object.to_a.map(&:to_h)
+  end
+end

data/lib/how_is/report/html.rb

@@ -0,0 +1,7 @@
+module HowIs
+  class HtmlReport < BaseReport
+    def export!(&block)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/how_is/report/json.rb

@@ -0,0 +1,13 @@
+module HowIs
+  class JsonReport < BaseReport
+    def export(&block)
+      to_json
+    end
+
+    def export!(file, &block)
+      File.open(file, 'w') do |f|
+        f.write export
+      end
+    end
+  end
+end

data/lib/how_is/report/pdf.rb

@@ -0,0 +1,66 @@
+module HowIs
+  class PdfReport < BaseReport
+    attr_accessor :pdf
+
+    def title(_text)
+      pdf.pad_bottom(10) {
+        pdf.text(_text, size: 25)
+      }
+    end
+
+    def header(_text)
+      pdf.pad_top(15) {
+        pdf.pad_bottom(3) {
+          pdf.text _text, size: 20
+        }
+      }
+    end
+
+    def horizontal_bar_graph(data)
+      filename_base = "./issues-per-label"
+      dat_file = filename_base + '.dat'
+      png_file = filename_base + '.png'
+
+      File.open(dat_file, 'w') do |f|
+        data.each_with_index do |(label, n), i|
+          f.puts "#{i}\t#{n}\t\"#{label}\""
+        end
+      end
+
+      Chart.gnuplot(label_font_size: 10,
+                    font_size: 16,
+                    data_file: dat_file,
+                    png_file: png_file)
+     Chart.rotate(90, png_file)
+
+      pdf.image png_file
+    end
+
+    def text(_text)
+      pdf.text _text
+    end
+
+    # Prawn (afaict) doesn't let you export to a binary blob.
+    # So export to a file, then read the file.
+    def export(&block)
+      # TODO: Use actual temporary file.
+      export!('temp.pdf', &block)
+
+      open('temp.pdf').read
+    end
+
+    def export!(file, &block)
+      _self = self
+
+      Prawn::Document.generate(file) do |pdf|
+        _self.pdf = pdf
+
+        pdf.font("Helvetica")
+
+        pdf.span(450, position: :center) do
+          _self.instance_eval(&block)
+        end
+      end
+    end
+  end
+end

data/lib/how_is/report.rb

@@ -0,0 +1,80 @@
+module HowIs
+  class UnsupportedExportFormat < StandardError
+    def initialize(format)
+      super("Unsupported export format: #{format}")
+    end
+  end
+
+  ##
+  # Represents a completed report.
+  class BaseReport < Struct.new(:analysis)
+    def to_h
+      analysis.to_h
+    end
+    alias :to_hash :to_h
+
+    def to_json
+      to_h.to_json
+    end
+
+    private
+      def issue_or_pr_summary(type, type_label)
+        oldest_date_format = "%b %e, %Y"
+        a = analysis
+
+        number_of_type = a.send("number_of_#{type}s")
+
+        "There are #{number_of_type} #{type_label}s open. " +
+        "The average #{type_label} age is #{a.send("average_#{type}_age")}, and the " +
+        "oldest was opened on #{a.send("oldest_#{type}_date").strftime(oldest_date_format)}."
+      end
+  end
+
+  class Report
+    require 'how_is/report/pdf'
+    require 'how_is/report/json'
+
+    REPORT_BLOCK = proc do
+      title "How is #{analysis.repository}?"
+
+      header "Pull Requests"
+      text issue_or_pr_summary "pull", "pull request"
+
+      header "Issues"
+      text issue_or_pr_summary "issue", "issue"
+
+      header "Issues Per Label"
+      issues_per_label = analysis.issues_with_label.to_a.sort_by { |(k, v)| v.to_i }.reverse
+      issues_per_label << ["(No label)", analysis.issues_with_no_label]
+      horizontal_bar_graph issues_per_label
+    end
+
+    def self.export(analysis, format = :pdf)
+
+    end
+
+    def self.export!(analysis, file)
+      format = file.split('.').last
+      report = get_report_class(format).new(analysis)
+
+      report.export!(file, &REPORT_BLOCK)
+    end
+
+    def self.export(analysis, format = :pdf)
+      report = get_report_class(format).new(analysis)
+
+      report.export(&REPORT_BLOCK)
+
+      report
+    end
+
+  private
+    def self.get_report_class(format)
+      class_name = "#{format.capitalize}Report"
+
+      raise UnsupportedExportFormat, format unless HowIs.const_defined?(class_name)
+
+      HowIs.const_get(class_name)
+    end
+  end
+end

data/lib/how_is/reporter.rb

@@ -0,0 +1,19 @@
+require 'contracts'
+require 'prawn'
+require 'how_is/chart'
+
+module HowIs
+  class Reporter
+    require 'how_is/report'
+    include Contracts::Core
+
+    ##
+    # Given an Analysis, generate a Report
+    #
+    # Returns a class that inherits from Report.
+    Contract Analysis, String => C::Any
+    def call(analysis, report_file)
+      Report.export!(analysis, report_file)
+    end
+  end
+end

data/lib/how_is/version.rb

@@ -0,0 +1,3 @@
+module HowIs
+  VERSION = "1.0.0"
+end

data/lib/how_is.rb

@@ -0,0 +1,32 @@
+require 'how_is/version'
+require 'contracts'
+
+C = Contracts
+
+module HowIs
+  include Contracts::Core
+
+  require 'how_is/fetcher'
+  require 'how_is/analyzer'
+  require 'how_is/reporter'
+
+  Contract C::KeywordArgs[repository: String, report_file: String,
+                          from_file: C::Optional[C::Or[String, nil]],
+                          fetcher: C::Optional[Class],
+                          analyzer: C::Optional[Class],
+                          reporter: C::Optional[Class]] => C::Any
+  def self.generate_report(repository:, report_file:,
+        from_file: nil,
+        fetcher:  Fetcher.new,
+        analyzer: Analyzer.new,
+        reporter: Reporter.new)
+    if from_file
+      analysis = analyzer.from_file(from_file)
+    else
+      raw_data = fetcher.call(repository)
+      analysis = analyzer.call(raw_data)
+    end
+
+    reporter.call(analysis, report_file)
+  end
+end

data/roadmap.markdown

@@ -0,0 +1,49 @@
+# How_is Roadmap
+
+A brief overview of how_is' goals and current status.
+
+## Goals
+
+How_is is intended to be usable both as a standalone program and a as library, with reports generated as either files or Ruby Strings. Initial export formats supported will be JSON and PDF, with HTML to follow later. When exporting a report, you can use the data from a previous JSON export to avoid making network requests.
+
+Metrics will be divided into two categories during implementation: Simple and Complex. Simple ones will be implementable using only the information gathered from one API call to the issue tracker. Complex metrics require things like cloning the repository or making multiple API requests.
+
+Simple metrics will include:
+
+* number of open Issues,
+* number of open Pull Requests,
+* number of issues associated with each label, as well as the number associated with no label,
+* average Issue age,
+* average Pull Request age,
+* date oldest Issue was opened,
+* date oldest Pull Request was opened.
+
+Complex metrics will include:
+
+* code churn (code change over time),
+* average response time by a team member in the past week,
+* graph of average response time by a team member per week.
+
+These metrics serve to either quantify the state of the repository, quantify the state of the codebase itself, or both. By quantifying the state of the issue tracker and codebase, it will hopefully be easier to decide what needs to be done.
+
+Once HTML export is implemented, a web service is planned to be created which tracks these metrics over time for the RubyGems repository. The details of this have not been fully fleshed out, but I am attempting to design the library in such a way to allow the flexibility required to do this.
+
+## Current Status
+
+As of June 15th 2016, how_is supports exports to JSON or PDF, but not HTML. For JSON and PDF, all Simple metrics have been implemented in some form, although they made need some polish ([#8](https://github.com/duckinator/how_is/issues/8)). HTML export is not implemented, and no Complex metrics are implemented. Tracking the number of issues without labels has also not been implemented ([#1](https://github.com/duckinator/how_is/issues/1)).
+
+Exporting to Ruby Strings that contain valid JSON, PDF, or HTML documents has also not been implemented ([#7](https://github.com/duckinator/how_is/issues/7)).
+
+Authentication is not being used, but will likely be necessary, as it would raise the API rate limits ([#6](https://github.com/duckinator/how_is/issues/6)).
+
+### Requirements for 1.0
+
+Once JSON and PDF exports are fully implemented ([#1](https://github.com/duckinator/how_is/issues/1)) and the README has a proper list of the metrics covered, v1.0 will be released.
+
+### Requirements for 2.0
+
+Once everything required for v1.0 as well as exporting to Strings ([#7](https://github.com/duckinator/how_is/issues/7)) has been implemented, v2.0 will be released.
+
+### Other changes
+
+All other changes ([#8](https://github.com/duckinator/how_is/issues/8), [#6](https://github.com/duckinator/how_is/issues/6), any changes without an accompanying issue) will be grouped together in either the next major release, or a separate minor release.

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification
+name: how_is
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ellen Marie Dash
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: github_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+- !ruby/object:Gem::Dependency
+  name: configru
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+- !ruby/object:Gem::Dependency
+  name: contracts
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: prawn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mini_magick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- me@duckie.co
+executables:
+- how_is
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- data/issues.plg
+- exe/how_is
+- how_is.gemspec
+- lib/how_is.rb
+- lib/how_is/analyzer.rb
+- lib/how_is/chart.rb
+- lib/how_is/fetcher.rb
+- lib/how_is/report.rb
+- lib/how_is/report/html.rb
+- lib/how_is/report/json.rb
+- lib/how_is/report/pdf.rb
+- lib/how_is/reporter.rb
+- lib/how_is/version.rb
+- roadmap.markdown
+homepage: https://github.com/duckinator/how_is
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.3
+signing_key: 
+specification_version: 4
+summary: Quantify the health of a GitHub repository is.
+test_files: []