jirametrics 2.2.1 → 2.3

data/lib/jirametrics/file_config.rb

@@ -5,10 +5,11 @@ require 'csv'
 class FileConfig
   attr_reader :project_config, :issues
 
-  def initialize project_config:, block:
+  def initialize project_config:, block:, today: Date.today
     @project_config = project_config
     @block = block
     @columns = nil
+    @today = today
   end
 
   def run
@@ -18,11 +19,8 @@ class FileConfig
     if @columns
       all_lines = prepare_grid
 
-      File.open(output_filename, 'w') do |file|
-        all_lines.each do |output_line|
-          file.puts CSV.generate_line(output_line)
-        end
-      end
+      content = all_lines.collect { |line| CSV.generate_line line }.join
+      project_config.exporter.file_system.save_file content: content, filename: output_filename
     elsif @html_report
       @html_report.run
     else
@@ -59,7 +57,7 @@ class FileConfig
     segments = []
     segments << project_config.target_path
     segments << project_config.file_prefix
-    segments << (@file_suffix || "-#{Date.today}.csv")
+    segments << (@file_suffix || "-#{@today}.csv")
     segments.join
   end
 

data/lib/jirametrics/file_system.rb

@@ -5,17 +5,26 @@ require 'json'
 class FileSystem
   attr_accessor :logfile, :logfile_name
 
+  # Effectively the same as File.read except it forces the encoding to UTF-8
+  def load filename
+    File.read filename, encoding: 'UTF-8'
+  end
+
   def load_json filename, fail_on_error: true
     return nil if fail_on_error == false && File.exist?(filename) == false
 
-    JSON.parse File.read(filename)
+    JSON.parse load(filename)
   end
 
   def save_json json:, filename:
+    save_file content: JSON.pretty_generate(compress json), filename: filename
+  end
+
+  def save_file content:, filename:
     file_path = File.dirname(filename)
     FileUtils.mkdir_p file_path unless File.exist?(file_path)
 
-    File.write(filename, JSON.pretty_generate(compress json))
+    File.write(filename, content)
   end
 
   def log message

data/lib/jirametrics/groupable_issue_chart.rb

@@ -5,10 +5,8 @@ require 'jirametrics/grouping_rules'
 
 module GroupableIssueChart
   def init_configuration_block user_provided_block, &default_block
-    if user_provided_block
-      instance_eval(&user_provided_block)
-      return if @group_by_block
-    end
+    instance_eval(&user_provided_block)
+    return if @group_by_block
 
     instance_eval(&default_block)
   end

data/lib/jirametrics/hierarchy_table.rb

@@ -3,15 +3,15 @@
 require 'jirametrics/chart_base'
 
 class HierarchyTable < ChartBase
-  def initialize block = nil
+  def initialize block
     super()
 
     header_text 'Hierarchy Table'
-    description_text <<-HTML
-      <p>content goes here</p>
+    description_text <<~HTML
+      <p>Shows all issues through this time period and the full hierarchy of their parents.</p>
     HTML
 
-    instance_eval(&block) if block
+    instance_eval(&block)
   end
 
   def run

data/lib/jirametrics/html/aging_work_table.erb

@@ -7,7 +7,7 @@
       <th>Issue</th>
       <th>Status</th>
       <th>Fix versions</th>
-      <% if any_scrum_boards? %>
+      <% if any_scrum_boards %>
         <th>Sprints</th>
       <% end %>
       <th><%= aggregated_project? ? 'Board' : 'Who' %></th>
@@ -40,9 +40,9 @@
             </div>
           <% end %>
         </td>
-        <td><%= format_status issue.status.name, board: issue.board %><%= unmapped_status_text(issue) unless current_status_visible? issue %></td>
+        <td><%= format_status issue.status.name, board: issue.board %></td>
         <td><%= fix_versions_text(issue) %></td>
-        <% if any_scrum_boards? %>
+        <% if any_scrum_boards %>
           <td><%= sprints_text(issue) %></td>
         <% end %>
         <td><%= aggregated_project? ? issue.board.name : issue.assigned_to %></td>

data/lib/jirametrics/html_report_config.rb

@@ -9,18 +9,45 @@ class HtmlReportConfig
 
   attr_reader :file_config, :sections
 
+  def self.define_chart name:, classname:, deprecated_warning: nil, deprecated_date: nil
+    lines = []
+    lines << "def #{name} &block"
+    lines << '  block = ->(_) {} unless block'
+    if deprecated_warning
+      lines << "  deprecated date: #{deprecated_date.inspect}, message: #{deprecated_warning.inspect}"
+    end
+    lines << "  execute_chart #{classname}.new(block)"
+    lines << 'end'
+    module_eval lines.join("\n"), __FILE__, __LINE__
+  end
+
+  define_chart name: 'aging_work_bar_chart', classname: 'AgingWorkBarChart'
+  define_chart name: 'aging_work_table', classname: 'AgingWorkTable'
+  define_chart name: 'cycletime_scatterplot', classname: 'CycletimeScatterplot'
+  define_chart name: 'daily_wip_chart', classname: 'DailyWipChart'
+  define_chart name: 'daily_wip_by_age_chart', classname: 'DailyWipByAgeChart'
+  define_chart name: 'daily_wip_by_blocked_stalled_chart', classname: 'DailyWipByBlockedStalledChart'
+  define_chart name: 'daily_wip_by_parent_chart', classname: 'DailyWipByParentChart'
+  define_chart name: 'throughput_chart', classname: 'ThroughputChart'
+  define_chart name: 'expedited_chart', classname: 'ExpeditedChart'
+  define_chart name: 'cycletime_histogram', classname: 'CycletimeHistogram'
+  define_chart name: 'estimate_accuracy_chart', classname: 'EstimateAccuracyChart'
+  define_chart name: 'hierarchy_table', classname: 'HierarchyTable'
+
+  define_chart name: 'daily_wip_by_type', classname: 'DailyWipChart',
+    deprecated_warning: 'This is the same as daily_wip_chart. Please use that one', deprecated_date: '2024-05-23'
+  define_chart name: 'story_point_accuracy_chart', classname: 'EstimateAccuracyChart',
+    deprecated_warning: 'Renamed to estimate_accuracy_chart. Please use that one', deprecated_date: '2024-05-23'
+
   def initialize file_config:, block:
     @file_config = file_config
     @block = block
-    # @cycletimes = []
     @sections = []
   end
 
   def cycletime label = nil, &block
-    # TODO: This is about to become deprecated
-
     @file_config.project_config.all_boards.each_value do |board|
-      raise 'Multiple cycletimes not supported yet' if board.cycletime
+      raise 'Multiple cycletimes not supported' if board.cycletime
 
       board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
     end
@@ -39,21 +66,36 @@ class HtmlReportConfig
     execute_chart DataQualityReport.new(@original_issue_times || {})
     @sections.rotate!(-1)
 
-    File.open @file_config.output_filename, 'w' do |file|
-      html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
-      css = load_css html_directory: html_directory
-      erb = ERB.new File.read(File.join(html_directory, 'index.erb'))
-      file.puts erb.result(binding)
-    end
+    html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
+    css = load_css html_directory: html_directory
+    erb = ERB.new file_system.load(File.join(html_directory, 'index.erb'))
+    file_system.save_file content: erb.result(binding), filename: @file_config.output_filename
+  end
+
+  def file_system
+    @file_config.project_config.exporter.file_system
+  end
+
+  def log message
+    file_system.log message
   end
 
   def load_css html_directory:
-    base_css = File.read(File.join(html_directory, 'index.css'))
+    base_css_filename = File.join(html_directory, 'index.css')
+    base_css = file_system.load(base_css_filename)
+    log("Loaded CSS:  #{base_css_filename}")
+
     extra_css_filename = settings['include_css']
-    return base_css unless extra_css_filename && File.exist?(extra_css_filename)
+    if extra_css_filename
+      if File.exist?(extra_css_filename)
+        base_css << "\n\n" << file_system.load(extra_css_filename)
+        log("Loaded CSS:  #{extra_css_filename}")
+      else
+        log("Unable to find specified CSS file: #{extra_css_filename}")
+      end
+    end
 
-    @file_config.project_config.exporter.file_system.log("including css from file: #{extra_css_filename}")
-    base_css << "\n\n" << File.read(extra_css_filename)
+    base_css
   end
 
   def board_id id = nil
@@ -66,6 +108,8 @@ class HtmlReportConfig
   end
 
   def aging_work_in_progress_chart board_id: nil, &block
+    block ||= ->(_) {}
+
     if board_id.nil?
       ids = issues.collect { |i| i.board.id }.uniq.sort
     else
@@ -79,50 +123,6 @@ class HtmlReportConfig
     end
   end
 
-  def aging_work_bar_chart &block
-    execute_chart AgingWorkBarChart.new(block)
-  end
-
-  def aging_work_table &block
-    execute_chart AgingWorkTable.new(block)
-  end
-
-  def cycletime_scatterplot &block
-    execute_chart CycletimeScatterplot.new block
-  end
-
-  def daily_wip_chart &block
-    execute_chart DailyWipChart.new(block)
-  end
-
-  def daily_wip_by_age_chart &block
-    execute_chart DailyWipByAgeChart.new block
-  end
-
-  def daily_wip_by_type &block
-    execute_chart DailyWipChart.new block
-  end
-
-  def daily_wip_by_blocked_stalled_chart
-    execute_chart DailyWipByBlockedStalledChart.new
-  end
-
-  def daily_wip_by_parent_chart &block
-    execute_chart DailyWipByParentChart.new block
-  end
-
-  def throughput_chart &block
-    execute_chart ThroughputChart.new(block)
-  end
-
-  def expedited_chart
-    execute_chart ExpeditedChart.new
-  end
-
-  def cycletime_histogram &block
-    execute_chart CycletimeHistogram.new block
-  end
-
   def random_color
     "##{Random.bytes(3).unpack1('H*')}"
   end
@@ -140,14 +140,6 @@ class HtmlReportConfig
     end
   end
 
-  def story_point_accuracy_chart &block
-    execute_chart StoryPointAccuracyChart.new block
-  end
-
-  def hierarchy_table &block
-    execute_chart HierarchyTable.new block
-  end
-
   def discard_changes_before_hook issues_cutoff_times
     # raise 'Cycletime must be defined before using discard_changes_before' unless @cycletime
 
@@ -173,6 +165,7 @@ class HtmlReportConfig
   def execute_chart chart, &after_init_block
     project_config = @file_config.project_config
 
+    chart.file_system = file_system
     chart.issues = issues
     chart.time_range = project_config.time_range
     chart.timezone_offset = timezone_offset
@@ -199,19 +192,13 @@ class HtmlReportConfig
     @file_config.issues
   end
 
+  # For use by the user config
   def find_board id
     @file_config.project_config.all_boards[id]
   end
 
-  def project_name
-    @file_config.project_config.name
-  end
-
+  # For use by the user config
   def boards
     @file_config.project_config.board_configs.collect(&:id).collect { |id| find_board id }
   end
-
-  def find_project_by_name name
-    @file_config.project_config.exporter.project_configs.find { |p| p.name == name }
-  end
 end

data/lib/jirametrics/issue.rb

@@ -35,16 +35,6 @@ class Issue
     raise "Unable to initialize #{raw['key']}"
   end
 
-  def sort_changes!
-    @changes.sort! do |a, b|
-      # It's common that a resolved will happen at the same time as a status change.
-      # Put them in a defined order so tests can be deterministic.
-      compare = a.time <=> b.time
-      compare = 1 if compare.zero? && a.resolution?
-      compare
-    end
-  end
-
   def key = @raw['key']
 
   def type = @raw['fields']['issuetype']['name']
@@ -53,9 +43,7 @@ class Issue
 
   def summary = @raw['fields']['summary']
 
-  def status
-    Status.new raw: @raw['fields']['status']
-  end
+  def status = Status.new(raw: @raw['fields']['status'])
 
   def labels = @raw['fields']['labels'] || []
 
@@ -69,37 +57,13 @@ class Issue
   end
 
   def key_as_i
-    $1.to_i if key =~ /-(\d+)$/
+    key =~ /-(\d+)$/ ? $1.to_i : 0
   end
 
   def component_names
     @raw['fields']['components']&.collect { |component| component['name'] } || []
   end
 
-  def fabricate_change field_name:
-    first_status = nil
-    first_status_id = nil
-
-    created_time = parse_time @raw['fields']['created']
-    first_change = @changes.find { |change| change.field == field_name }
-    if first_change.nil?
-      # There have been no changes of this type yet so we have to look at the current one
-      return nil unless @raw['fields'][field_name]
-
-      first_status = @raw['fields'][field_name]['name']
-      first_status_id = @raw['fields'][field_name]['id'].to_i
-    else
-      # Otherwise, we look at what the first one had changed away from.
-      first_status = first_change.old_value
-      first_status_id = first_change.old_value_id
-    end
-    ChangeItem.new time: created_time, artificial: true, author: author, raw: {
-      'field' => field_name,
-      'to' => first_status_id,
-      'toString' => first_status
-    }
-  end
-
   def first_time_in_status *status_names
     @changes.find { |change| change.current_status_matches(*status_names) }&.time
   end
@@ -195,7 +159,7 @@ class Issue
   end
 
   def created
-    # This shouldn't be necessary and yet we've seen one case where it was.
+    # This nil check shouldn't be necessary and yet we've seen one case where it was.
     parse_time @raw['fields']['created'] if @raw['fields']['created']
   end
 
@@ -478,6 +442,31 @@ class Issue
     comparison
   end
 
+  def dump
+    result = +''
+    result << "#{key} (#{type}): #{compact_text summary, 200}\n"
+
+    assignee = raw['fields']['assignee']
+    result << "  [assignee] #{assignee['name'].inspect} <#{assignee['emailAddress']}>\n" unless assignee.nil?
+
+    raw['fields']['issuelinks'].each do |link|
+      result << "  [link] #{link['type']['outward']} #{link['outwardIssue']['key']}\n" if link['outwardIssue']
+      result << "  [link] #{link['type']['inward']} #{link['inwardIssue']['key']}\n" if link['inwardIssue']
+    end
+    changes.each do |change|
+      value = change.value
+      old_value = change.old_value
+
+      message = "  [change] #{change.time} [#{change.field}] "
+      message << "#{compact_text(old_value).inspect} -> " unless old_value.nil? || old_value.empty?
+      message << compact_text(value).inspect
+      message << " (#{change.author})"
+      message << ' <<artificial entry>>' if change.artificial?
+      result << message << "\n"
+    end
+    result
+  end
+
   private
 
   def assemble_author raw
@@ -508,4 +497,46 @@ class Issue
       @changes << ChangeItem.new(raw: raw, time: created, author: author, artificial: true)
     end
   end
+
+  def compact_text text, max = 60
+    return nil if text.nil?
+
+    text = text.gsub(/\s+/, ' ').strip
+    text = "#{text[0..max]}..." if text.length > max
+    text
+  end
+
+  def sort_changes!
+    @changes.sort! do |a, b|
+      # It's common that a resolved will happen at the same time as a status change.
+      # Put them in a defined order so tests can be deterministic.
+      compare = a.time <=> b.time
+      compare = 1 if compare.zero? && a.resolution?
+      compare
+    end
+  end
+
+  def fabricate_change field_name:
+    first_status = nil
+    first_status_id = nil
+
+    created_time = parse_time @raw['fields']['created']
+    first_change = @changes.find { |change| change.field == field_name }
+    if first_change.nil?
+      # There have been no changes of this type yet so we have to look at the current one
+      return nil unless @raw['fields'][field_name]
+
+      first_status = @raw['fields'][field_name]['name']
+      first_status_id = @raw['fields'][field_name]['id'].to_i
+    else
+      # Otherwise, we look at what the first one had changed away from.
+      first_status = first_change.old_value
+      first_status_id = first_change.old_value_id
+    end
+    ChangeItem.new time: created_time, artificial: true, author: author, raw: {
+      'field' => field_name,
+      'to' => first_status_id,
+      'toString' => first_status
+    }
+  end
 end

data/lib/jirametrics/project_config.rb

@@ -49,7 +49,7 @@ class ProjectConfig
   end
 
   def load_settings
-    JSON.parse(File.read(File.join(__dir__, 'settings.json')))
+    JSON.parse(file_system.load(File.join(__dir__, 'settings.json')))
   end
 
   def guess_project_id
@@ -89,6 +89,8 @@ class ProjectConfig
     raise 'Not allowed to have both an aggregate and a download section. Pick only one.' if @download_config
 
     @aggregate_config = AggregateConfig.new project_config: self, block: block
+
+    # Processing of aggregates should only happen during the export
     return if @exporter.downloading?
 
     @aggregate_config.evaluate_next_level
@@ -120,7 +122,7 @@ class ProjectConfig
 
   def load_board board_id:, filename:
     board = Board.new(
-      raw: JSON.parse(File.read(filename)), possible_statuses: @possible_statuses
+      raw: JSON.parse(file_system.load(filename)), possible_statuses: @possible_statuses
     )
     board.project_config = self
     @all_boards[board_id] = board
@@ -162,7 +164,7 @@ class ProjectConfig
     # We may not always have this file. Load it if we can.
     return unless File.exist? filename
 
-    statuses = JSON.parse(File.read(filename))
+    statuses = JSON.parse(file_system.load(filename))
       .map { |snippet| Status.new(raw: snippet) }
     statuses
       .find_all { |status| status.global? }
@@ -178,7 +180,7 @@ class ProjectConfig
 
       board_id = $1.to_i
       timezone_offset = exporter.timezone_offset
-      JSON.parse(File.read("#{target_path}#{file}"))['values'].each do |json|
+      JSON.parse(file_system.load("#{target_path}#{file}"))['values'].each do |json|
         @all_boards[board_id].sprints << Sprint.new(raw: json, timezone_offset: timezone_offset)
       end
     end
@@ -231,7 +233,7 @@ class ProjectConfig
 
   def load_project_metadata
     filename = "#{@target_path}/#{file_prefix}_meta.json"
-    json = JSON.parse(File.read(filename))
+    json = JSON.parse(file_system.load(filename))
 
     @data_version = json['version'] || 1
 
@@ -360,7 +362,7 @@ class ProjectConfig
     default_board = nil
 
     group_filenames_and_board_ids(path: path).each do |filename, board_ids|
-      content = File.read(File.join(path, filename))
+      content = file_system.load(File.join(path, filename))
       if board_ids == :unknown
         boards = [(default_board ||= find_default_board)]
       else
@@ -435,4 +437,8 @@ class ProjectConfig
     end
     exporter.file_system.log "Discarded data from #{issues_cutoff_times.count} issues out of a total #{issues.size}"
   end
+
+  def file_system
+    @exporter.file_system
+  end
 end

data/lib/jirametrics/sprint_burndown.rb

@@ -108,6 +108,17 @@ class SprintBurndown < ChartBase
     result
   end
 
+  def sprints_in_time_range board
+    board.sprints.select do |sprint|
+      sprint_end_time = sprint.completed_time || sprint.end_time
+      sprint_start_time = sprint.start_time
+      next false if sprint_start_time.nil?
+
+      time_range.include?(sprint_start_time) || time_range.include?(sprint_end_time) ||
+        (sprint_start_time < time_range.begin && sprint_end_time > time_range.end)
+    end || []
+  end
+
   # select all the changes that are relevant for the sprint. If this issue never appears in this sprint then return [].
   def changes_for_one_issue issue:, sprint:
     story_points = 0.0

data/lib/jirametrics/status_collection.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+class StatusNotFoundError < StandardError
+end
+
 class StatusCollection
   def initialize
     @list = []
@@ -32,7 +35,7 @@ class StatusCollection
           next
         else
           all_status_names = @list.collect { |s| "#{s.name.inspect}:#{s.id.inspect}" }.uniq.sort.join(', ')
-          raise "Status not found: \"#{name_or_id}\". Possible statuses are: #{all_status_names}"
+          raise StatusNotFoundError, "Status not found: \"#{name_or_id}\". Possible statuses are: #{all_status_names}"
         end
       end
 

data/lib/jirametrics/throughput_chart.rb

@@ -5,7 +5,7 @@ class ThroughputChart < ChartBase
 
   attr_accessor :possible_statuses
 
-  def initialize block = nil
+  def initialize block
     super()
 
     header_text 'Throughput Chart'

data/lib/jirametrics.rb

@@ -61,7 +61,7 @@ class JiraMetrics < Thor
     require 'jirametrics/trend_line_calculator'
     require 'jirametrics/status'
     require 'jirametrics/issue_link'
-    require 'jirametrics/story_point_accuracy_chart'
+    require 'jirametrics/estimate_accuracy_chart'
     require 'jirametrics/status_collection'
     require 'jirametrics/sprint'
     require 'jirametrics/issue'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: '2.3'
 platform: ruby
 authors:
 - Mike Bowler
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-16 00:00:00.000000000 Z
+date: 2024-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: random-word
@@ -87,11 +87,10 @@ files:
 - lib/jirametrics/discard_changes_before.rb
 - lib/jirametrics/download_config.rb
 - lib/jirametrics/downloader.rb
+- lib/jirametrics/estimate_accuracy_chart.rb
 - lib/jirametrics/examples/aggregated_project.rb
 - lib/jirametrics/examples/standard_project.rb
 - lib/jirametrics/expedited_chart.rb
-- lib/jirametrics/experimental/generator.rb
-- lib/jirametrics/experimental/info.rb
 - lib/jirametrics/exporter.rb
 - lib/jirametrics/file_config.rb
 - lib/jirametrics/file_system.rb
@@ -107,12 +106,12 @@ files:
 - lib/jirametrics/html/cycletime_scatterplot.erb
 - lib/jirametrics/html/daily_wip_chart.erb
 - lib/jirametrics/html/data_quality_report.erb
+- lib/jirametrics/html/estimate_accuracy_chart.erb
 - lib/jirametrics/html/expedited_chart.erb
 - lib/jirametrics/html/hierarchy_table.erb
 - lib/jirametrics/html/index.css
 - lib/jirametrics/html/index.erb
 - lib/jirametrics/html/sprint_burndown.erb
-- lib/jirametrics/html/story_point_accuracy_chart.erb
 - lib/jirametrics/html/throughput_chart.erb
 - lib/jirametrics/html_report_config.rb
 - lib/jirametrics/issue.rb
@@ -127,7 +126,6 @@ files:
 - lib/jirametrics/sprint_issue_change_data.rb
 - lib/jirametrics/status.rb
 - lib/jirametrics/status_collection.rb
-- lib/jirametrics/story_point_accuracy_chart.rb
 - lib/jirametrics/throughput_chart.rb
 - lib/jirametrics/tree_organizer.rb
 - lib/jirametrics/trend_line_calculator.rb
@@ -155,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Extract Jira metrics