how_is 10.0.0 → 11.0.0

data/how_is.gemspec

@@ -35,4 +35,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 11.2"
   spec.add_development_dependency "rspec", "~> 3.5"
   spec.add_development_dependency "timecop", "~> 0.8.1"
+  spec.add_development_dependency "vcr", "~> 3.0"
+  spec.add_development_dependency "webmock"
 end

data/lib/how_is/analyzer.rb

@@ -12,12 +12,16 @@ module HowIs
   class Analyzer
     include Contracts::Core
 
+    ##
+    # Raised when attempting to export to an unsupported format.
     class UnsupportedImportFormat < StandardError
       def initialize(format)
         super("Unsupported import format: #{format}")
       end
     end
 
+    ##
+    # Generates and returns an analysis.
     Contract Fetcher::Results, C::KeywordArgs[analysis_class: C::Optional[Class]] => Analysis
     def call(data, analysis_class: Analysis)
       issues = data.issues
@@ -43,6 +47,8 @@ module HowIs
       )
     end
 
+    ##
+    # Generates an analysis from a JSON report.
     def from_file(file)
       extension = file.split('.').last
       raise UnsupportedImportFormat, extension unless extension == 'json'
@@ -82,10 +88,13 @@ module HowIs
       hash
     end
 
+    # Returns the number of issues with no label.
     def num_with_no_label(issues)
       issues.select { |x| x['labels'].empty? }.length
     end
 
+    # Given an Array of dates, average the timestamps and return the date that
+    # represents.
     def average_date_for(issues_or_pulls)
       timestamps = issues_or_pulls.map { |iop| Date.parse(iop['created_at']).strftime('%s').to_i }
       average_timestamp = timestamps.reduce(:+) / issues_or_pulls.length
@@ -94,7 +103,10 @@ module HowIs
     end
 
     # Given an Array of issues or pulls, return the average age of them.
+    # Returns nil if no issues or pulls are provided.
     def average_age_for(issues_or_pulls)
+      return nil if issues_or_pulls.empty?
+
       ages = issues_or_pulls.map {|iop| time_ago_in_seconds(iop['created_at'])}
       raw_average = ages.reduce(:+) / ages.length
 
@@ -136,15 +148,21 @@ module HowIs
     end
 
     # Given an Array of issues or pulls, return the creation date of the oldest.
+    # Returns nil if no issues or pulls are provided.
     def oldest_for(issues_or_pulls)
+      return nil if issues_or_pulls.empty?
+
       issues_or_pulls.sort_by {|x| DateTime.parse(x['created_at']) }.first
     end
 
+    # Given an issue or PR, returns the date it was created.
     def date_for(issue_or_pull)
       DateTime.parse(issue_or_pull['created_at'])
     end
 
   private
+    # Takes an Array of labels, and returns amodified list that includes links
+    # to each label.
     def with_label_links(labels, repository)
       labels.map do |label, num_issues|
         label_link = "https://github.com/#{repository}/issues?q=" + CGI.escape("is:open is:issue label:\"#{label}\"")
@@ -153,11 +171,14 @@ module HowIs
       end.to_h
     end
 
+    # Returns how many seconds ago a date (as a String) was.
     def time_ago_in_seconds(x)
       DateTime.now.strftime("%s").to_i - DateTime.parse(x).strftime("%s").to_i
     end
 
     def issue_or_pull_to_hash(iop)
+      return nil if iop.nil?
+
       ret = {}
 
       ret['html_url'] = iop['html_url']

data/lib/how_is/cli/parser.rb

@@ -22,14 +22,16 @@ class HowIs::CLI
   class Parser
     attr_reader :opts
 
+    # Parses +argv+ to generate an options Hash to control the behavior of
+    # the library.
     def call(argv)
       opts = Slop::Options.new
       opts.banner =
         <<-EOF.gsub(/ *\| ?/, '')
-        | Usage: how_is REPOSITORY [--report REPORT_FILE]
+        | Usage: how_is REPOSITORY [--report REPORT_FILE] [--from JSON_FILE]
         |        how_is --config CONFIG_FILE
         |
-        | Where REPOSITORY is of the format <GitHub username or org>/<repository name>.
+        | Where REPOSITORY is <GitHub username or org>/<repository name>.
         | CONFIG_FILE defaults to how_is.yml.
         |
         | E.g., if you wanted to check https://github.com/how-is/how_is,
@@ -53,28 +55,33 @@ class HowIs::CLI
 
       options[:report] ||= DEFAULT_REPORT_FILE
 
-      # The following are only useful if true.
+      # The following are only useful if they're not nil or false.
       # Removing them here simplifies contracts and keyword args for other APIs.
       options.delete(:config)   unless options[:config]
       options.delete(:help)     unless options[:help]
       options.delete(:version)  unless options[:version]
 
+      # Raise an exception if the file can't be exported.
       unless HowIs.can_export_to?(options[:report])
         raise InvalidOutputFileError, "Invalid file: #{options[:report_file]}. Supported formats: #{HowIs.supported_formats.join(', ')}"
       end
 
-      if options[:config]
-        # Nothing to do.
-      elsif options[:from]
-        # Opening this file here seems a bit messy, but it works.
-        raise InvalidInputFileError, "No such file: #{options[:from]}" unless File.file?(options[:from])
-
-        options[:repository] = JSON.parse(open(options[:from_file]).read)['repository']
-        raise InvalidInputFileError, "Invalid JSON report file." unless options[:repository]
-      elsif argv.length >= 1
-        options[:repository] = argv.delete_at(0)
-      else
-        raise NoRepositoryError, "No repository specified."
+      unless options[:config]
+        # If we pass --config, other options (excluding --help and --version)
+        # are ignored. As such, everything in this `unless` block is irrelevant.
+
+        if options[:from]
+          raise InvalidInputFileError, "No such file: #{options[:from]}" unless File.file?(options[:from])
+
+          # Opening the file here is a bit gross, but I couldn't find a better
+          # way to do it. -@duckinator
+          options[:repository] = JSON.parse(open(options[:from_file]).read)['repository']
+          raise InvalidInputFileError, "Invalid JSON report file." unless options[:repository]
+        elsif argv.length >= 1
+          options[:repository] = argv.delete_at(0)
+        else
+          raise NoRepositoryError, "No repository specified."
+        end
       end
 
       {

data/lib/how_is/cli.rb

@@ -28,12 +28,16 @@ class HowIs::CLI
     YAML.dump(frontmatter)
   end
 
+  ##
+  # Generates a series of report files based on a YAML config file.
   def from_config_file(config_file = nil, **kwargs)
     config_file ||= DEFAULT_CONFIG_FILE
 
     from_config(YAML.load_file(config_file), **kwargs)
   end
 
+  ##
+  # Generates a series of report files based on a config Hash.
   def from_config(config,
         github: nil,
         report_class: nil)
@@ -67,6 +71,8 @@ class HowIs::CLI
     end
   end
 
+  # Combine the frontmatter, report data, and raw report into a report with
+  # frontmatter.
   def build_report(frontmatter, report_data, report)
     str = StringIO.new
 

data/lib/how_is/fetcher.rb

@@ -24,6 +24,8 @@ class HowIs::Fetcher
   end
 
 
+  ##
+  # Fetches repository information from GitHub and returns a Results object.
   Contract String, C::Or[C::RespondTo[:issues, :pulls], nil] => Results
   def call(repository,
         github = nil)
@@ -39,7 +41,8 @@ class HowIs::Fetcher
     )
   end
 
-  private def obj_to_array_of_hashes(object)
+private
+  def obj_to_array_of_hashes(object)
     object.to_a.map(&:to_h)
   end
 end

data/lib/how_is/pulse.rb

@@ -14,8 +14,16 @@ module HowIs
     end
 
     def html_summary
-      @pulse_page_response.body
-        .split('<div class="section diffstat-summary">').last
+      parts = 
+        @pulse_page_response.body
+          .split('<div class="section diffstat-summary">')
+
+      if parts.length == 1
+        return "There hasn't been any activity on #{@repository} in the last month."
+      end
+
+      parts
+        .last
         .split('</div>').first
         .gsub('<a href="/', '<a href="https://github.com/')
         .strip

data/lib/how_is/report/html.rb

@@ -38,7 +38,7 @@ module HowIs
         if row[2]
           label_text = link(row[0], row[2])
         else
-          label_text = row[1]
+          label_text = row[0]
         end
 
         @r += <<-EOF
@@ -60,7 +60,7 @@ module HowIs
       instance_exec(&block)
     end
 
-    def export!(file, &block)
+    def export_file(file, &block)
       report = export(&block)
 
       File.open(file, 'w') do |f|

data/lib/how_is/report/json.rb

@@ -8,7 +8,7 @@ module HowIs
       to_json
     end
 
-    def export!(file, &block)
+    def export_file(file, &block)
       File.open(file, 'w') do |f|
         f.write export
       end

data/lib/how_is/report.rb

@@ -1,3 +1,6 @@
+require 'date'
+require 'how_is/pulse'
+
 module HowIs
   class UnsupportedExportFormat < StandardError
     def initialize(format)
@@ -27,6 +30,14 @@ module HowIs
     end
 
     private
+    def pluralize(text, number)
+      number == 1 ? text : "#{text}s"
+    end
+
+    def are_is(number)
+      number == 1 ? "is" : "are"
+    end
+
     def issue_or_pr_summary(type, type_label)
       oldest_date_format = "%b %e, %Y"
       a = analysis
@@ -36,20 +47,39 @@ module HowIs
       type_link = a.send("#{type}s_url")
       oldest = a.send("oldest_#{type}")
 
-      "There are #{link("#{number_of_type} #{type_label}s open", type_link)}. " +
-      "The average #{type_label} age is #{a.send("average_#{type}_age")}, and the " +
-      "#{link("oldest", oldest['html_url'])} was opened on #{oldest['date'].strftime(oldest_date_format)}."
+      if number_of_type == 0
+        "There are #{link("no #{type_label}s open", type_link)}."
+      else
+        "There #{are_is(number_of_type)} #{link("#{number_of_type} #{pluralize(type_label, number_of_type)} open", type_link)}. " +
+        "The average #{type_label} age is #{a.send("average_#{type}_age")}, and the " +
+        "#{link("oldest", oldest['html_url'])} was opened on #{oldest['date'].strftime(oldest_date_format)}."
+      end
     end
   end
 
   class Report
-    require 'how_is/report/pdf'
     require 'how_is/report/json'
     require 'how_is/report/html'
 
+    # The way this entire class works is there is a REPORT_BLOCK proc which
+    # calls various methods to create the report, and REPORT_BLOCK is eventually
+    # instance_exec'd by the various *Report (HtmlReport, previously PdfReport)
+    # classes, which define the methods required.
+    #
+    # The *Report class inherit from BaseReport, which implements the common
+    # methods for them.
+
     REPORT_BLOCK = proc do
       title "How is #{analysis.repository}?"
 
+      # DateTime#new_offset(0) sets the timezone to UTC. I think it does this
+      # without changing anything besides the timezone, but who knows, 'cause
+      # new_offset is entirely undocumented! (Even though it's used in the
+      # DateTime documentation!)
+      #
+      # TODO: Stop pretending everyone who runs how_is is in UTC.
+      text "Monthly report, ending on #{DateTime.now.new_offset(0).strftime('%B %e, %Y')}."
+
       text github_pulse_summary
 
       header "Pull Requests"
@@ -67,13 +97,17 @@ module HowIs
       horizontal_bar_graph issues_per_label
     end
 
-    def self.export!(analysis, file)
+    ##
+    # 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, &REPORT_BLOCK)
+      report.export_file(file, &REPORT_BLOCK)
     end
 
+    ##
+    # Export a report to a String.
     def self.export(analysis, format = HowIs::DEFAULT_FORMAT)
       report = get_report_class(format).new(analysis)
 
@@ -81,6 +115,8 @@ module HowIs
     end
 
   private
+    # Given a format name (+format+), returns the corresponding <blah>Report
+    # class.
     def self.get_report_class(format)
       class_name = "#{format.capitalize}Report"
 

data/lib/how_is/version.rb

@@ -1,3 +1,3 @@
 module HowIs
-  VERSION = "10.0.0"
+  VERSION = "11.0.0"
 end

data/lib/how_is.rb

@@ -15,27 +15,37 @@ module HowIs
 
   DEFAULT_FORMAT = :html
 
+  ##
+  # Generate a report file.
   def self.generate_report_file(report:, **kw_args)
     analysis = self.generate_analysis(**kw_args)
 
-    Report.export!(analysis, report)
+    Report.export_file(analysis, report)
   end
 
+  ##
+  # Generates and returns a report as a String.
   def self.generate_report(format:, **kw_args)
     analysis = self.generate_analysis(**kw_args)
 
     Report.export(analysis, format)
   end
 
+  ##
+  # Returns a list of possible export formats.
   def self.supported_formats
     report_constants = HowIs.constants.grep(/.Report/) - [:BaseReport]
     report_constants.map {|x| x.to_s.split('Report').first.downcase }
   end
 
+  ##
+  # Returns whether or not the specified +file+ can be exported to.
   def self.can_export_to?(file)
+    # TODO: Check if the file is writable?
     supported_formats.include?(file.split('.').last)
   end
 
+  # Generate an analysis. Used internally for generate_report{,_file}.
   Contract C::KeywordArgs[repository: String,
                           from: C::Optional[C::Or[String, nil]],
                           fetcher: C::Optional[Class],

data/roadmap.markdown

@@ -1,14 +1,24 @@
 # How_is Roadmap
 
+2016-09-01
+
 A brief overview of how_is' goals and current status.
 
-## Goals
+## Current Progress
+
+So far, HTML and JSON reports work extremely well. PDF support has lagged
+due to difficulties finding a library that can do everything needed.
+There is [an integration test that fails for an unknown reason](https://github.com/how-is/how_is/issues/36).
 
-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.
+Reports can be generated using a config file, typically named
+how_is.yml. This has been successfully used for
+[how-is.github.io/how-is-rubygems](https://how-is.github.io/how-is-rubygems/)
+([how_is.yml source](https://github.com/how-is/how-is-rubygems/blob/gh-pages/how_is.yml)).
 
-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.
+how_is can be used as either an executable or a library, however
+[library usage is currently undocumented](https://github.com/how-is/how_is/issues/45).
 
-Simple metrics will include:
+Metrics that have been implemented include:
 
 * number of open Issues,
 * number of open Pull Requests,
@@ -18,6 +28,19 @@ Simple metrics will include:
 * date oldest Issue was opened,
 * date oldest Pull Request was opened.
 
+HTML reports contain a graph showing the issues assigned each label (or no
+label). PDF reports contain a less-nice variant of
+that graph.
+
+## Goals
+
+The next major steps are complex metrics and creating a web
+dashboard for multiple projects.
+
+Complex metrics require things like cloning the repository or making multiple API requests.
+
+### Complex Metrics
+
 Complex metrics will include:
 
 * code churn (code change over time),
@@ -26,24 +49,34 @@ Complex metrics will include:
 
 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)).
+### Dashboard
 
-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)).
+The end goal for the dashboard is to have a website where you can view
+information about multiple projects, and identify trends.
 
-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)).
+Currently, there is a way to generate reports based on a configuration
+file, which has been successfully used to generate [reports for RubyGems](https://how-is.github.io/how-is-rubygems/).
+However, these have to be manually generated each month.
 
-### Requirements for 1.0
+Idealy, these could be generated automatically, and would be stored in a
+database. Once that is done, the information can be more easily retrieved
+in groups and used to generate graphs or more complex summaries.
 
-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.
+## Milestones
 
-### Requirements for 2.0
+Before beginning work on the dashboard, the how_is APIs need to be
+documented and possibly cleaned up.
 
-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.
+Once that's done, the plan for beginning work on the dashboard is
+roughly:
 
-### Other changes
+1. decide what the dashboard will eventually contain,
+2. create a design for the finished dashboard (so we know what's being
+  worked towards),
+3. figure out the software architecture required to support this,
+4. determine what parts of the dashboard are currently implementable,
+5. create an intermediate design for what how_is can actually support
+  (this should be a subset of the original design).
 
-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.
+Once these have been done, it should be possible to have people work on
+the dashboard in parallel.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: how_is
 version: !ruby/object:Gem::Version
-  version: 10.0.0
+  version: 11.0.0
 platform: ruby
 authors:
 - Ellen Marie Dash
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-01 00:00:00.000000000 Z
+date: 2016-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: github_api
@@ -164,6 +164,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.1
+- !ruby/object:Gem::Dependency
+  name: vcr
+  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'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - me@duckie.co
@@ -176,6 +204,7 @@ files:
 - ".rspec"
 - ".rspec-ignore-tags"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -183,12 +212,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- data/issues.plg
 - exe/how_is
+- fixtures/vcr_cassettes/how_is-example-repository.yml
+- fixtures/vcr_cassettes/how_is-with-config-file.yml
 - how_is.gemspec
 - lib/how_is.rb
 - lib/how_is/analyzer.rb
-- lib/how_is/chart.rb
 - lib/how_is/cli.rb
 - lib/how_is/cli/parser.rb
 - lib/how_is/fetcher.rb
@@ -196,7 +225,6 @@ files:
 - 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/version.rb
 - roadmap.markdown
 homepage: https://github.com/duckinator/how_is
@@ -219,7 +247,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Quantify the health of a GitHub repository is.

data/data/issues.plg

@@ -1,22 +0,0 @@
-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