Class: HowIs

Inherits:
Object
  • Object
show all
Includes:
Contracts::Core
Defined in:
lib/how_is.rb,
lib/how_is/pulse.rb,
lib/how_is/report.rb,
lib/how_is/fetcher.rb,
lib/how_is/version.rb,
lib/how_is/analyzer.rb,
lib/how_is/report/html.rb,
lib/how_is/report/json.rb,
lib/how_is/contributions.rb,
lib/how_is/report/base_report.rb

Overview

HowIs control class used from the CLI tool.

Generates an analysis and has methods to build reports from it.

Defined Under Namespace

Classes: Analysis, Analyzer, BaseReport, CLI, Contributions, Fetcher, HtmlReport, JsonReport, Pulse, Report, UnsupportedExportFormat

Constant Summary collapse

DEFAULT_FORMAT = 
:html
VERSION = 
"18.1.0"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(repository, analysis = nil, **kw_args) ⇒ HowIs

Generate a HowIs instance, so you can generate reports.

Parameters:

  • repository (String) —

    The name of a GitHub repository (of the format <user or organization>/<repository>).

  • analysis (HowIs::Analysis) (defaults to: nil) —

    Optional; if passed, this Analysis object is used instead of generating one.



30
31
32
33
34
35
36
 
# File 'lib/how_is.rb', line 30

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

Class Method Details

.build_report(frontmatter, report_data, report) ⇒ Object

Combine the frontmatter, report data, and raw report into a report with frontmatter.



186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/how_is.rb', line 186

def self.build_report(frontmatter, report_data, report)
  str = StringIO.new

  if frontmatter
    str.puts generate_frontmatter(frontmatter, report_data)
    str.puts "---"
    str.puts
  end

  str.puts report

  str.string
end

.can_export_to?(file) ⇒ Boolean

Returns whether or not the specified file can be exported to.

Parameters:

  • file (String) —

    A filename.

Returns:

  • (Boolean) —

    true if HowIs can export to the file, false if it can’t.



94
95
96
97
 
# File 'lib/how_is.rb', line 94

def self.can_export_to?(file)
  # TODO: Check if the file is writable?
  supported_formats.include?(file.split(".").last)
end

.from_config(config, github: nil, report_class: nil) ⇒ Object

Generates a series of report files based on a config Hash.

Parameters:

  • config (Hash) —

    A Hash specifying the formats, locations, etc of the reports to generate.

  • github (You don't need this.) (defaults to: nil) —

    An object to replace the GitHub class when fetching data.

  • report_class (You don't need this.) (defaults to: nil) —

    An object to replace the HowIs::Report class when generating reports.



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/how_is.rb', line 148

def self.from_config(config,
      github: nil,
      report_class: nil)
  report_class ||= HowIs::Report

  date = Date.strptime(Time.now.to_i.to_s, "%s")
  friendly_date = date.strftime("%B %d, %y")

  analysis = HowIs.generate_analysis(repository: config["repository"], github: github)

  report_data = {
    repository: config["repository"],
    date: date,
    friendly_date: friendly_date,
  }

  generated_reports = {}

  config["reports"].map do |format, report_config|
    # Sometimes report_data has unused keys, which generates a warning, but
    # we're okay with it.
    filename = silence_warnings { report_config["filename"] % report_data }
    file = File.join(report_config["directory"], filename)

    report = report_class.export(analysis, format)

    result = build_report(report_config["frontmatter"], report_data, report)

    generated_reports[file] = result

    result
  end

  generated_reports
end

.from_hash(data) ⇒ HowIs

Given report data as a hash, create a new HowIs object (for generating other reports).

Parameters:

  • 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.



72
73
74
75
76
 
# File 'lib/how_is.rb', line 72

def self.from_hash(data)
  analysis = HowIs::Analyzer.from_hash(data)

  new(analysis.repository, analysis)
end

.from_json(json) ⇒ HowIs

Given a JSON report, create a new HowIs object (for generating other reports).

Parameters:

  • 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.



61
62
63
 
# File 'lib/how_is.rb', line 61

def self.from_json(json)
  from_hash(JSON.parse(json))
end

.generate_analysis(repository:, fetcher: Fetcher.new, analyzer: Analyzer.new, github: nil) ⇒ Object 



107
108
109
110
111
112
113
114
115
 
# File 'lib/how_is.rb', line 107

def self.generate_analysis(repository:,
      fetcher: Fetcher.new,
      analyzer: Analyzer.new,
      github: nil)
  raw_data = fetcher.call(repository, github)
  analysis = analyzer.call(raw_data)

  analysis
end

.generate_frontmatter(frontmatter, report_data) ⇒ Object 



124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/how_is.rb', line 124

def self.generate_frontmatter(frontmatter, report_data)
  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)
end

.supported_formats ⇒ Array<String>

Returns a list of possible export formats.

Returns:

  • (Array<String>) —

    An array of the types of reports you can generate.



83
84
85
86
 
# File 'lib/how_is.rb', line 83

def self.supported_formats
  report_constants = HowIs.constants.grep(/.Report/) - [:BaseReport]
  report_constants.map { |x| x.to_s.split("Report").first.downcase }
end

Instance Method Details

#to_html ⇒ String

Generate an HTML report.

Returns:

  • (String) —

    An HTML report.



42
43
44
 
# File 'lib/how_is.rb', line 42

def to_html
  Report.export(@analysis, :html)
end

#to_json ⇒ String

Generate a JSON report.

Returns:

  • (String) —

    A JSON report.



50
51
52
 
# File 'lib/how_is.rb', line 50

def to_json
  Report.export(@analysis, :json)
end