how_is 17.0.0 → 18.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 71e52f74ab14a10f79d1fcebd73a3e44a2a8860a
-  data.tar.gz: 93b67eedce8aeab93e266db7524f66e139059a1f
+  metadata.gz: 0c44d90a04abb7343c89a5ff858d63d23c98c0ce
+  data.tar.gz: e2c1842533e09ec46d26d5cc6d5e24c72c2c65f2
 SHA512:
-  metadata.gz: 0010c1c0d71fd9560ce5ece88e9366e87481eb28f933833807db62ad0e7384da502265461f087d9372cb029077afd8d9c111f47f55ab596455817ab5f928e8a2
-  data.tar.gz: d7441138e3ebb82e4d66703492d28268550203503284c6e591a6147a779da9261ef24f2d3447564e09f4abee1dc1b3346c71a35c53751cbe56e41ed21a422fc8
+  metadata.gz: 77dea4e880e70869bc7b9ad6a3ce2cd2d33cd20a07cfd5ebbf45e01937275fe828b7e448bfcbf0c93486720202c44244065da82b5251b0423358efcdd174905d
+  data.tar.gz: 41c3d52d430ec1de181d01461db6b084e14ccbf3d50e147e72306f85214b367bb718d059199edb2ee9cc09f412c93e5b1c30b5e66b45a2bf53b6aa5481abc0e7

data/CHANGELOG.md

@@ -9,6 +9,41 @@ this project adheres to [Semantic Versioning](http://semver.org).
 
 (Nothing so far.)
 
+## [v18.0.0]
+
+This release ([snapshot](https://github.com/how-is/how_is/tree/v18.0.0))
+vastly improves documentation, fixes the `--from` flag, and adds the
+`HowIs.from_hash` method (used by the
+[dashboard](https://github.com/how-is/dashboard)).
+
+Pull Requests for this release can be [viewed on
+GitHub](https://github.com/how-is/how_is/pulls?utf8=&q=is%3Apr%20created%3A2017-02-10..2017-03-03).
+
+### Additions
+
+* Add/improve inline code documentation.
+  ([#132](https://github.com/how-is/how_is/pull/132))
+* Move documentation from design/ to README.
+  ([#143](https://github.com/how-is/how_is/pull/143))
+* Add `HowIs.from_hash` method.
+  ([#144](https://github.com/how-is/how_is/pull/144))
+
+### Changes
+
+* Unpin Rack version. ([#139](https://github.com/how-is/how_is/pull/139))
+* Fix --from. ([#141](https://github.com/how-is/how_is/pull/141))
+
+### Miscellaneous
+
+Things that don't affect users of how\_is.
+
+* Fix grammar in gemspec.
+  ([#129](https://github.com/how-is/how_is/pull/129))
+* Fix URL in gemspec. ([#130](https://github.com/how-is/how_is/pull/130))
+* Remove shebang line from lib/ file.
+  ([#131](https://github.com/how-is/how_is/pull/131))
+
+
 ## [v17.0.0]
 
 This release ([snapshot](https://github.com/how-is/how_is/tree/v17.0.0))

data/README.md

@@ -34,9 +34,28 @@ E.g.,
 
 The above command creates a HTML file containing the summary at `./report.html`.
 
+If you don't pass the `--report` flag, it defaults to
+`./report.html`.
+
+#### Generating reports, using a JSON report as a cache
+
+You can use a JSON report as a cache when generating another rpeort.
+
+E.g.,
+
+    $ how_is rubygems/rubygems --report report.json
+    $ how_is --from report.json --report report.html
+
+The first command generates a JSON report at `./report.json`. The second
+command generates an HTML report at `./report.html`, using information
+from `./report.json`.
+
+When using `--from`, no network requests are made, because all of the
+required information is in the JSON report.
+
 #### Generating reports from a config file
 
-Beyond the above, you can also create a config file — typically called
+You can also create a config file — typically called
 how_is.yml — and run `how_is --config YAML_CONFIG_FILE`. (E.g., if
 the config file is how_is.yml, you would run `how_is --config how_is.yml`.)
 

data/design/01-functionality.md

@@ -91,65 +91,7 @@ Items with two asterisks (\*\*) have been partially implemented.
 
 ## UI Specification
 
-## Infmation about how_is
-
-`how_is --help` prints help text and exits.
-
-`how_is --version` prints the version and exits.
-
-### Generating a report
-
-How\_is can generate HTML reports for https://github.com/rubygems/rubygems.
-By default, it generates reports at `./report.html`.
-To view an HTML report, open it in aweb browser.
-
-There is no output when it succeeds.
-
-```
-$ how_is rubygems/rubygems
-$
-```
-
-### Generate a report, specifying the filename
-
-You can generate reports with other filenames, as well as different
-report formats, using the `--report FILENAME` parameter.
-
-The FILENAME can be any filename that ends with a lowercase
-extension specifying a supported format (currently `.html` and `.json`).
-
-If the filename ends with `.html` it'll generate an HTML report,
-if it ends with `.json` it'll generate a JSON report.
-
-There is no output when it succeeds.
-
-```
-$ how_is --report report.json rubygems/rubygems
-$
-```
-
-### Generate a report, using data from a JSON report
-
-If you have a JSON report (see above), you can use that to generate
-another report (probably HTML) using that data.
-
-E.g.,
-
-```
-$ how_is --from report.json --report report.html
-$
-```
-
-This generates an HTML report just like `how_is --report report.html
-REPOSITORY`, except it uses the data from `report.json` instead of
-fetching it again.
-
-tl;dr: you're using the JSON file as a cache.
-
-### Generating a report using a config file
-
-See [the README](https://github.com/how-is/how_is/blob/master/README.md#generating-reports-from-a-config-file).
-
-### Ruby API
-
-See [the README](https://github.com/how-is/how_is/blob/master/README.md#ruby-api).
+how_is follows [Readme Driven
+Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) and, as such,
+[README.md](https://github.com/how-is/how_is/blob/master/README.md) is
+both the documentation and the specification.

data/exe/how_is

@@ -18,16 +18,41 @@ opts      = result[:opts]
 options   = result[:options]
 arguments = result[:arguments]
 
+if options[:help]
+  puts result[:opts]
+  exit
+elsif options[:version]
+  puts HowIs::VERSION
+  exit
+end
+
+def save_files(reports)
+  reports.each do |file, report|
+    format = file.split('.').last
+
+    File.open(file, 'w') do |f|
+      f.write report.send("to_#{format}")
+    end
+  end
+end
+
 begin
-  if options[:help]
-    puts result[:opts]
-  elsif options[:version]
-    puts HowIs::VERSION
-  elsif options[:config]
-    HowIs.from_config_file(YAML.load_file(options[:config]))
+  if options[:config]
+    reports = HowIs.from_config_file(YAML.load_file(options[:config]))
+
+    save_files(reports)
   else
-    HowIs.generate_report_file(options)
+    report =
+      if options[:from]
+        json_report = File.open(options[:from]).read
+        HowIs.from_json(json_report)
+      else
+        HowIs.new(options[:repository])
+      end
+
+    save_files({ options[:report] => report })
   end
+
 rescue => e
   if ENV['SHOW_TRACE']
     raise

data/how_is.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   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.summary       = %q{Quantify the health of a GitHub repository.}
+  spec.homepage      = "https://github.com/how-is/how_is"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -22,8 +22,6 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "contracts", "~> 0.14.0"
   spec.add_runtime_dependency "slop", "~> 4.4.1"
 
-  spec.add_runtime_dependency "rack", "~> 2.0"
-
   spec.add_runtime_dependency "tessellator-fetcher", "~> 5.0.0"
 
   spec.add_development_dependency "bundler", "~> 1.11"

data/lib/how_is/analyzer.rb

@@ -21,7 +21,11 @@ class HowIs
     end
 
     ##
-    # Generates and returns an analysis.
+    # Generates and returns an analysis.i
+    #
+    # @param data [Fetcher::Results] The results gathered by Fetcher.
+    # @param analysis_class (You don't need this.) A class to use instead of
+    #   HowIs::Analysis.
     Contract Fetcher::Results, C::KeywordArgs[analysis_class: C::Optional[Class]] => Analysis
     def call(data, analysis_class: Analysis)
       issues = data.issues
@@ -53,10 +57,11 @@ class HowIs
     end
 
     ##
-    # Generates an analysis from a JSON report.
-    def self.from_json(json)
-      hash = JSON.parse(json)
-      hash = hash.map do |k, v|
+    # Generates an analysis from a hash of report data.
+    #
+    # @param data [Hash] The hash to generate an Analysis from.
+    def self.from_hash(data)
+      hash = data.map do |k, v|
         v = DateTime.parse(v) if k.end_with?('_date')
 
         [k, v]

data/lib/how_is/cli.rb

@@ -1,20 +1,24 @@
-#!/usr/bin/env ruby
-
 require "how_is"
 require "slop"
 
 class HowIs::CLI
   DEFAULT_REPORT_FILE = "report.#{HowIs::DEFAULT_FORMAT}"
 
+  # Parent class of all exceptions raised in HowIs::CLI.
   class OptionsError < StandardError
   end
 
+  # Raised when the specified output file can't be used.
   class InvalidOutputFileError < OptionsError
   end
 
+  # Raised when the specified input file doesn't contain
+  # a valid JSON report.
   class InvalidInputFileError < OptionsError
   end
 
+  # Raised when no repository is specified, but one is required.
+  # (It's _not_ required, e.g., when +--config+ is passed.)
   class NoRepositoryError < OptionsError
   end
 
@@ -25,6 +29,8 @@ class HowIs::CLI
     # the library.
     def call(argv)
       opts = Slop::Options.new
+
+      # General usage information.
       opts.banner =
         <<-EOF.gsub(/ *\| ?/, '')
         | Usage: how_is REPOSITORY [--report REPORT_FILE] [--from JSON_FILE]
@@ -41,48 +47,64 @@ class HowIs::CLI
       opts.separator ""
       opts.separator "Options:"
 
+      # Allowed arguments:
       opts.bool   "-h", "--help",    "Print help text"
       opts.string       "--config",  "YAML config file, used to generate a group of reports"
       opts.string       "--from",    "JSON report file, used instead of fetching the data again"
       opts.string       "--report",  "output file for the report (valid extensions: #{HowIs.supported_formats.join(', ')}; default: #{DEFAULT_REPORT_FILE})"
       opts.bool   "-v", "--version", "prints the version"
 
+      # Parse the arguments.
       parser    = Slop::Parser.new(opts)
       result    = parser.parse(argv)
+
+      # +options+ is a Hash of flags/values.
       options   = result.to_hash
+      # +arguments+ is an Array of values that don't correspond to a flag.
       arguments = result.arguments
 
+      # If --report isn't specified, default to DEFAULT_REPORT_FILE.
       options[:report] ||= DEFAULT_REPORT_FILE
 
       # The following are only useful if they're not nil or false.
-      # Removing them here simplifies contracts and keyword args for other APIs.
+      # 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.
+      # 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_file]}. Supported formats: #{HowIs.supported_formats.join(', ')}"
       end
 
+      # If we pass --config, other options (excluding --help and
+      # --version) are ignored. As such, when --config is passed,
+      # everything in this `unless` block is irrelevant.
       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']
+          # 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]).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
 
+      # 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,

data/lib/how_is/pulse.rb

@@ -1,18 +1,23 @@
 require 'tessellator/fetcher'
 
 class HowIs
-  # This entire class is a monstrous hack, because GitHub doesn't provide a good
-  # API for Pulse.
+  # This entire class is a monstrous hack, because GitHub doesn't provide
+  # a good API for Pulse.
+  #
+  # TODO: Use GitHub's Statistics API to replace this garbage.
+  #   See https://github.com/how-is/how_is/issues/122
   class Pulse
     def initialize(repository)
       @repository = repository
       @pulse_page_response = fetch_pulse!(repository)
     end
 
+    # This is probably dead code.
     def text_summary
       raise NotImplementedError
     end
 
+    # Gets the HTML Pulse summary.
     def html_summary
       parts = 
         @pulse_page_response.body
@@ -30,6 +35,7 @@ class HowIs
     end
 
   private
+    # Fetch Pulse page from GitHub for scraping.
     def fetch_pulse!(repository, period='monthly')
       Tessellator::Fetcher.new.call('get', "https://github.com/#{repository}/pulse/#{period}")
     end

data/lib/how_is/report/base_report.rb

@@ -38,40 +38,62 @@ class HowIs
       @r
     end
 
+    # === Methods implemented by subclasses of BaseReport ===
 
-    
+    ##
+    # Returns the format of report this class generates.
+    #
+    # @returns [Symbol] A lowercase symbol denoting the report format.
     def format
       raise NotImplementedError
     end
 
+    ##
+    # Appends a title to the report.
     def title(_text)
       raise NotImplementedError
     end
 
+    ##
+    # Appends a header to the report.
     def header(_text)
       raise NotImplementedError
     end
 
+    ##
+    # Appends a line of text to the report.
     def text(_text)
       raise NotImplementedError
     end
 
+    ##
+    # Appends a link to the report.
     def link(_text, url)
       raise NotImplementedError
     end
 
+    ##
+    # Appends an unordered list to the report.
     def unordered_list(arr)
       raise NotImplementedError
     end
 
+    ##
+    # Appends a horizontal bar graph to the report.
     def horizontal_bar_graph(data)
       raise NotImplementedError
     end
 
+    ##
+    # Exports the report as a String.
     def export
       raise NotImplementedError
     end
 
+    ##
+    # Exports a report to a file.
+    #
+    # NOTE: May be removed in the future.
     def export_file(file)
       raise NotImplementedError
     end

data/lib/how_is/report/json.rb

@@ -1,15 +1,28 @@
 require 'how_is/report/base_report'
 
 class HowIs
+  ##
+  # A JSON report.
   class JsonReport < BaseReport
+    # A JSON report is simply a JSON dump of the corresponding
+    # HowIs::Analysis instance.
+
+    ##
+    # The format of the report.
+    #
+    # @return [Symbol] The name of the format.
     def format
       :json
     end
 
+    ##
+    # Generates a report.
     def export
       to_json
     end
 
+    ##
+    # Generates a report and writes it to a file.
     def export_file(file)
       File.open(file, 'w') do |f|
         f.write export

data/lib/how_is/version.rb

@@ -1,3 +1,3 @@
 class HowIs
-  VERSION = "17.0.0"
+  VERSION = "18.0.0"
 end

data/lib/how_is.rb

@@ -16,36 +16,65 @@ class HowIs
   DEFAULT_FORMAT = :html
 
   ##
-  # Generate a report file.
-  def self.generate_report_file(report:, **kw_args)
-    analysis = self.generate_analysis(**kw_args)
-
-    Report.export_file(analysis, report)
-  end
-
-  ##
-  # Generates and returns a report as a String.
+  # Generate a HowIs instance, so you can generate reports.
+  #
+  # @param repository [String] The name of a GitHub repository (of the
+  #   format <user or organization>/<repository>).
+  # @param analysis [HowIs::Analysis] Optional; if passed, this Analysis
+  #   object is used instead of generating one.
   def initialize(repository, analysis = nil, **kw_args)
+    # If no Analysis is passed, generate one.
     analysis ||= HowIs.generate_analysis(repository: repository, **kw_args)
+
+    # Used by to_html, to_json, etc.
     @analysis = analysis
   end
 
+  ##
+  # Generate an HTML report.
+  #
+  # @returns [String] An HTML report.
   def to_html
     Report.export(@analysis, :html)
   end
 
+  ##
+  # Generate a JSON report.
+  #
+  # @returns [String] A JSON report.
   def to_json
     Report.export(@analysis, :json)
   end
 
+  ##
+  # Given a JSON report, create a new HowIs object (for generating other
+  # reports).
+  #
+  # @param json [String] A JSON report object.
+  # @returns [HowIs] A HowIs object that can be used for generating other
+  #   reports, treating the JSON report as a cache.
   def self.from_json(json)
-    analysis = HowIs::Analyzer.from_json(json)
+    self.from_hash(JSON.parse(json))
+  end
+
+  ##
+  # Given report data as a hash, create a new HowIs object (for generating
+  # other reports).
+  #
+  # @param data [Hash] A hash containing report data.
+  # @returns [HowIs] A HowIs object that can be used for generating other
+  #   reports, treating the provided report data as a cache.
+  def self.from_hash(data)
+    analysis = HowIs::Analyzer.from_hash(data)
 
     self.new(analysis.repository, analysis)
   end
 
   ##
   # Returns a list of possible export formats.
+  #
+  # @returns [Array<String>] An array of the types of reports you can
+  #   generate.
   def self.supported_formats
     report_constants = HowIs.constants.grep(/.Report/) - [:BaseReport]
     report_constants.map {|x| x.to_s.split('Report').first.downcase }
@@ -53,28 +82,27 @@ class HowIs
 
   ##
   # Returns whether or not the specified +file+ can be exported to.
+  #
+  # @param file [String] A filename.
+  # @returns [Boolean] +true+ if HowIs can export to the file, +false+
+  #   if it can't.
   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}.
+  # Generate an analysis.
+  # TODO: This may make more sense as Analysis.new().
   Contract C::KeywordArgs[repository: String,
-                          from: C::Optional[C::Or[String, nil]],
                           fetcher: C::Optional[Class],
                           analyzer: C::Optional[Class],
                           github: C::Optional[C::Any]] => C::Any
   def self.generate_analysis(repository:,
-        from: nil,
         fetcher: Fetcher.new,
         analyzer: Analyzer.new,
         github: nil)
-    if from
-      analysis = analyzer.from_file(from)
-    else
-      raw_data = fetcher.call(repository, github)
-      analysis = analyzer.call(raw_data)
-    end
+    raw_data = fetcher.call(repository, github)
+    analysis = analyzer.call(raw_data)
 
     analysis
   end
@@ -101,6 +129,13 @@ class HowIs
 
   ##
   # Generates a series of report files based on a config Hash.
+  #
+  # @param config [Hash] A Hash specifying the formats, locations, etc
+  #   of the reports to generate.
+  # @param github (You don't need this.) An object to replace the GitHub
+  #   class when fetching data.
+  # @param report_class (You don't need this.) An object to replace the
+  #   HowIs::Report class when generating reports.
   def self.from_config(config,
         github: nil,
         report_class: nil)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: how_is
 version: !ruby/object:Gem::Version
-  version: 17.0.0
+  version: 18.0.0
 platform: ruby
 authors:
 - Ellen Marie Dash
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-09 00:00:00.000000000 Z
+date: 2017-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: github_api
@@ -52,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 4.4.1
-- !ruby/object:Gem::Dependency
-  name: rack
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: tessellator-fetcher
   requirement: !ruby/object:Gem::Requirement
@@ -203,7 +189,7 @@ files:
 - lib/how_is/report/json.rb
 - lib/how_is/version.rb
 - roadmap.markdown
-homepage: https://github.com/duckinator/how_is
+homepage: https://github.com/how-is/how_is
 licenses:
 - MIT
 metadata: {}
@@ -223,8 +209,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.4.5.2
 signing_key: 
 specification_version: 4
-summary: Quantify the health of a GitHub repository is.
+summary: Quantify the health of a GitHub repository.
 test_files: []