jirametrics 2.14 → 2.22

data/lib/jirametrics/html/sprint_burndown.erb

@@ -1,5 +1,6 @@
 <h2>Burndown by <%= y_axis_title %></h2>
 
+<%= seam_start %>
 <div class="chart">
   <canvas id="<%= chart_id %>" width="<%= canvas_width %>" height="<%= canvas_height %>"></canvas>
 </div>
@@ -63,16 +64,20 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
   }
 });
 </script>
+<%= seam_end %>
 
 <%
   link_id = next_id
   issues_id = next_id
 %>
-[<a id='<%= link_id %>' href="#" onclick='expand_collapse("<%= link_id %>", "<%= issues_id %>"); return false;'>Show details</a>]
-<div id="<%= issues_id %>" style="display: none;">
+<section>
+<div class='foldable startFolded'>Show statistics</div>
+<div id="<%= issues_id %>">
+<%= seam_start 'stats_table' %>
 <table class='standard' style="margin-left: 1em;">
   <thead>
     <th>Sprint</th>
+    <th>Length</th>
     <th>State</th>
     <th>Started</th>
     <th>Completed</th>
@@ -85,6 +90,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
     <% @summary_stats.keys.sort_by(&:start_time).each do |sprint| %>
       <tr>
         <td><%= sprint.name %></td>
+        <td><%= sprint.day_count %></td>
         <td><%= sprint.raw['state'] %></td>
         <% stats = @summary_stats[sprint] %>
         <td><%= stats.started %></td>
@@ -101,6 +107,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
     <% end %>
   </tbody>
 </table>
+<%= seam_end 'stats_table' %>
 
 <p>Legend:
   <ul>
@@ -109,4 +116,5 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
     <% end %>
   </ul>
 </p>
-</div>
+</div>
+</section>

data/lib/jirametrics/html/throughput_chart.erb

@@ -1,4 +1,4 @@
-
+<%= seam_start %>
 <div class="chart">
   <canvas id="<%= chart_id %>" width="<%= canvas_width %>" height="<%= canvas_height %>"></canvas>
 </div>
@@ -59,4 +59,4 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
   }
 });
 </script>
-
+<%= seam_end %>

data/lib/jirametrics/html_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class HtmlGenerator
+  attr_accessor :file_system, :settings
+
+  def create_html output_filename:, settings:
+    @settings = settings
+    html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
+    css = load_css html_directory: html_directory
+    javascript = file_system.load(File.join(html_directory, 'index.js'))
+    erb = ERB.new file_system.load(File.join(html_directory, 'index.erb'))
+    file_system.save_file content: erb.result(binding), filename: output_filename
+  end
+
+  def load_css html_directory:
+    base_css_filename = File.join(html_directory, 'index.css')
+    base_css = file_system.load(base_css_filename)
+
+    extra_css_filename = settings['include_css']
+    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
+
+    base_css
+  end
+end

data/lib/jirametrics/html_report_config.rb

@@ -3,7 +3,7 @@
 require 'erb'
 require 'jirametrics/self_or_issue_dispatcher'
 
-class HtmlReportConfig
+class HtmlReportConfig < HtmlGenerator
   include SelfOrIssueDispatcher
 
   attr_reader :file_config, :sections, :charts
@@ -51,7 +51,10 @@ class HtmlReportConfig
     @file_config.project_config.all_boards.each_value do |board|
       raise 'Multiple cycletimes not supported' if board.cycletime
 
-      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block, file_system: file_system)
+      board.cycletime = CycleTimeConfig.new(
+        possible_statuses: file_config.project_config, label: label, block: block,
+        file_system: file_system, settings: settings
+      )
     end
   end
 
@@ -70,10 +73,7 @@ class HtmlReportConfig
 
     html create_footer
 
-    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
+    create_html output_filename: @file_config.output_filename, settings: settings
   end
 
   def file_system
@@ -84,24 +84,6 @@ class HtmlReportConfig
     file_system.log message
   end
 
-  def load_css html_directory:
-    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']
-    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
-
-    base_css
-  end
-
   def board_id id
     @board_id = id
   end
@@ -160,7 +142,7 @@ class HtmlReportConfig
     chart.time_range = project_config.time_range
     chart.timezone_offset = timezone_offset
     chart.settings = settings
-    chart.users = project_config.users
+    chart.atlassian_document_format = project_config.atlassian_document_format
 
     chart.all_boards = project_config.all_boards
     chart.board_id = find_board_id
@@ -173,6 +155,7 @@ class HtmlReportConfig
     after_init_block&.call chart
 
     @charts << chart
+    chart.before_run
     html chart.run
   end
 

data/lib/jirametrics/issue.rb

@@ -19,9 +19,10 @@ class Issue
 
     # There are cases where we create an Issue of fragments like linked issues and those won't have
     # changelogs.
-    return unless @raw['changelog']
+    load_history_into_changes if @raw['changelog']
 
-    load_history_into_changes
+    # As above with fragments, there may not be a fields section
+    return unless @raw['fields']
 
     # If this is an older pull of data then comments may not be there.
     load_comments_into_changes if @raw['fields']['comment']
@@ -152,7 +153,7 @@ class Issue
   # Are we currently in this status? If yes, then return the most recent status change.
   def currently_in_status *status_names
     change = most_recent_status_change
-    return false if change.nil?
+    return nil if change.nil?
 
     change if change.current_status_matches(*status_names)
   end
@@ -162,7 +163,7 @@ class Issue
     category_ids = find_status_category_ids_by_names category_names
 
     change = most_recent_status_change
-    return false if change.nil?
+    return nil if change.nil?
 
     status = find_or_create_status id: change.value_id, name: change.value
     change if status && category_ids.include?(status.category.id)
@@ -211,8 +212,91 @@ class Issue
     first_time_in_status(*board.visible_columns.collect(&:status_ids).flatten)
   end
 
+  # If this issue will ever be in an active sprint then return the time that it
+  # was first added to that sprint, whether or not the sprint was active at that
+  # time. Although it seems like an odd thing to calculate, it's a reasonable proxy
+  # for 'ready' in cases where the team doesn't have an explicit 'ready' status.
+  # You'd be better off with an explicit 'ready' but sometimes that's not an option.
+  def first_time_added_to_active_sprint
+    unless board.scrum?
+      raise 'first_time_added_to_active_sprint() can only be used with Scrum boards: ' \
+          "issue=#{key}, board=#{board.inspect}"
+    end
+    data_clazz = Struct.new(:sprint_id, :sprint_start, :sprint_stop, :change)
+
+    matching_changes = []
+    all_datas = []
+
+    @changes.each do |change|
+      next unless change.sprint?
+
+      added_sprint_ids = change.value_id - change.old_value_id
+      added_sprint_ids.each do |id|
+        data = data_clazz.new
+        data.sprint_id = id
+        data.change = change
+        data.sprint_start, data.sprint_stop = find_sprint_start_end(sprint_id: id, change: change)
+        all_datas << data
+      end
+
+      removed_sprint_ids = change.old_value_id - change.value_id
+      removed_sprint_ids.each do |id|
+        data = all_datas.find { |d| d.sprint_id == id }
+        # It's possible for an issue to be created inside a sprint and therefore for
+        # that add-to-sprint not show in the history.
+        next unless data
+
+        all_datas.delete(data)
+        next if data.sprint_start.nil? || data.sprint_start >= change.time
+
+        matching_changes << data.change
+      end
+    end
+
+    # There can't be any more removes so whatever is left is a valid option
+    # Now all we care about is if the sprint has started.
+    all_datas.each do |data|
+      matching_changes << data.change if data.sprint_start
+    end
+
+    matching_changes.min_by(&:time)
+  end
+
+  def find_sprint_start_end sprint_id:, change:
+    # There are two different places that sprint data could be found. In theory all
+    # sprints would be found in both places. In practice, sometimes what we need is
+    # in one or the other but not both.
+
+    # First look in the actual sprints json. If any issues are in this sprint then it should
+    # be here.
+    sprint = board.sprints.find { |s| s.id == sprint_id }
+    return [sprint.start_time, sprint.completed_time] if sprint
+
+    # Then look at the sprints inside the issue. Even though the field id may be specified,
+    # that custom field may not be present. This happens if it was in that sprint but was
+    # then removed, whether or not that sprint had ever started.
+    sprint_data = raw['fields'][change.field_id]&.find { |sd| sd['id'].to_i == sprint_id }
+    if sprint_data
+      start = parse_time(sprint_data['startDate'])
+      stop = parse_time(sprint_data['completeDate'])
+      return [start, stop]
+    end
+
+    # If we got this far then the sprint can't be found anywhere, so we pretend that it never
+    # started. Is this guaranteed to be true? No. In theory if all issues were removed from
+    # an active sprint then it would also disappear, even though it had started. Nothing we
+    # can do to detect that edge-case though.
+    [nil, nil]
+  end
+
   def parse_time text
-    Time.parse(text).getlocal(@timezone_offset)
+    if text.nil?
+      nil
+    elsif text.is_a? String
+      Time.parse(text).getlocal(@timezone_offset)
+    else
+      Time.at(text / 1000).getlocal(@timezone_offset)
+    end
   end
 
   def created
@@ -220,6 +304,10 @@ class Issue
     parse_time @raw['fields']['created'] if @raw['fields']['created']
   end
 
+  def time_created
+    @changes.first
+  end
+
   def updated
     parse_time @raw['fields']['updated']
   end
@@ -233,11 +321,11 @@ class Issue
   end
 
   def assigned_to
-    @raw['fields']&.[]('assignee')&.[]('displayName')
+    @raw['fields']['assignee']&.[]('displayName')
   end
 
   def assigned_to_icon_url
-    @raw['fields']&.[]('assignee')&.[]('avatarUrls')&.[]('16x16')
+    @raw['fields']['assignee']&.[]('avatarUrls')&.[]('16x16')
   end
 
   # Many test failures are simply unreadable because the default inspect on this class goes
@@ -300,9 +388,7 @@ class Issue
     results
   end
 
-  def blocked_stalled_changes end_time:, settings: nil
-    settings ||= @board.project_config.settings
-
+  def blocked_stalled_statuses settings
     blocked_statuses = settings['blocked_statuses']
     stalled_statuses = settings['stalled_statuses']
     unless blocked_statuses.is_a?(Array) && stalled_statuses.is_a?(Array)
@@ -310,6 +396,14 @@ class Issue
         "stalled_statuses(#{stalled_statuses.inspect}) must both be arrays"
     end
 
+    [blocked_statuses, stalled_statuses]
+  end
+
+  def blocked_stalled_changes end_time:, settings: nil
+    settings ||= @board.project_config.settings
+
+    blocked_statuses, stalled_statuses = blocked_stalled_statuses(settings)
+
     blocked_link_texts = settings['blocked_link_text']
     stalled_threshold = settings['stalled_threshold_days']
     flagged_means_blocked = !!settings['flagged_means_blocked'] # rubocop:disable Style/DoubleNegation
@@ -608,7 +702,7 @@ class Issue
 
   def dump
     result = +''
-    result << "#{key} (#{type}): #{compact_text summary, 200}\n"
+    result << "#{key} (#{type}): #{compact_text summary, max: 200}\n"
 
     assignee = raw['fields']['assignee']
     result << "  [assignee] #{assignee['name'].inspect} <#{assignee['emailAddress']}>\n" unless assignee.nil?
@@ -705,6 +799,23 @@ class Issue
     board.sprints.select { |s| sprint_ids.include? s.id }
   end
 
+  def started_sprints
+    sprints.reject { |sprint| sprint.future? }
+  end
+
+  def compact_text text, max: 60
+    return '' if text.nil?
+
+    if text.is_a? Hash
+      # We can't effectively compact it but we can convert it into a string.
+      text = @board.project_config.atlassian_document_format.to_html(text)
+    else
+      text = text.gsub(/\s+/, ' ').strip
+      text = "#{text[0...max]}..." if text.length > max
+    end
+    text
+  end
+
   private
 
   def load_history_into_changes
@@ -729,14 +840,6 @@ class Issue
     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.
@@ -754,6 +857,9 @@ class Issue
     first_status = nil
     first_status_id = nil
 
+    # There won't be a created timestamp in cases where this was a linked issue
+    return unless @raw['fields']['created']
+
     created_time = parse_time @raw['fields']['created']
     first_change = @changes.find { |change| change.field == field_name }
     if first_change.nil?

data/lib/jirametrics/jira_gateway.rb

@@ -3,21 +3,61 @@
 require 'cgi'
 require 'json'
 require 'English'
+require 'open3'
 
 class JiraGateway
-  attr_accessor :ignore_ssl_errors, :jira_url
+  attr_accessor :ignore_ssl_errors
+  attr_reader :jira_url, :settings, :file_system
 
-  def initialize file_system:
+  def initialize file_system:, jira_config:, settings:
     @file_system = file_system
+    load_jira_config(jira_config)
+    @settings = settings
+    @ignore_ssl_errors = settings['ignore_ssl_errors']
+  end
+
+  def post_request relative_url:, payload:
+    command = make_curl_command url: "#{@jira_url}#{relative_url}", method: 'POST'
+    exec_and_parse_response command: command, stdin_data: payload
+  end
+
+  def exec_and_parse_response command:, stdin_data:
+    log_entry = "  #{command.gsub(/\s+/, ' ')}"
+    log_entry = sanitize_message log_entry
+    @file_system.log log_entry
+
+    stdout, stderr, status = capture3(command, stdin_data: stdin_data)
+    unless status.success?
+      @file_system.log "Failed call with exit status #{status.exitstatus}!"
+      @file_system.log "Returned (stdout): #{stdout.inspect}"
+      @file_system.log "Returned (stderr): #{stderr.inspect}"
+      raise "Failed call with exit status #{status.exitstatus}. " \
+        "See #{@file_system.logfile_name} for details"
+    end
+
+    @file_system.log "Returned (stderr): #{stderr.inspect}" unless stderr == ''
+    raise 'no response from curl on stdout' if stdout == ''
+
+    parse_response(command: command, result: stdout)
+  end
+
+  def capture3 command, stdin_data:
+    # In it's own method so we can mock it out in tests
+    Open3.capture3(command, stdin_data: stdin_data)
   end
 
   def call_url relative_url:
     command = make_curl_command url: "#{@jira_url}#{relative_url}"
-    result = call_command command
+    exec_and_parse_response command: command, stdin_data: nil
+  end
+
+  def parse_response command:, result:
     begin
       json = JSON.parse(result)
     rescue # rubocop:disable Style/RescueStandardError
-      raise "Error when parsing result: #{result.inspect}"
+      message = "Unable to parse results from #{sanitize_message(command)}"
+      @file_system.error message, more: result
+      raise message
     end
 
     raise "Download failed with: #{JSON.pretty_generate(json)}" unless json_successful?(json)
@@ -25,18 +65,11 @@ class JiraGateway
     json
   end
 
-  def call_command command
-    log_entry = "  #{command.gsub(/\s+/, ' ')}"
-    log_entry = log_entry.gsub(@jira_api_token, '[API_TOKEN]') if @jira_api_token
-    @file_system.log log_entry
+  def sanitize_message message
+    token = @jira_api_token || @jira_personal_access_token
+    return message unless token # cookie based authentication
 
-    result = `#{command}`
-    @file_system.log result unless $CHILD_STATUS.success?
-    return result if $CHILD_STATUS.success?
-
-    @file_system.log "Failed call with exit status #{$CHILD_STATUS.exitstatus}."
-    raise "Failed call with exit status #{$CHILD_STATUS.exitstatus}. " \
-      "See #{@file_system.logfile_name} for details"
+    message.gsub(token, '[API_TOKEN]')
   end
 
   def load_jira_config jira_config
@@ -56,7 +89,7 @@ class JiraGateway
     @cookies = (jira_config['cookies'] || []).collect { |key, value| "#{key}=#{value}" }.join(';')
   end
 
-  def make_curl_command url:
+  def make_curl_command url:, method: 'GET'
     command = +''
     command << 'curl'
     command << ' -L' # follow redirects
@@ -65,8 +98,13 @@ class JiraGateway
     command << " --cookie #{@cookies.inspect}" unless @cookies.empty?
     command << " --user #{@jira_email}:#{@jira_api_token}" if @jira_api_token
     command << " -H \"Authorization: Bearer #{@jira_personal_access_token}\"" if @jira_personal_access_token
-    command << ' --request GET'
+    command << " --request #{method}"
+    if method == 'POST'
+      command << ' --data @-'
+      command << ' --header "Content-Type: application/json"'
+    end
     command << ' --header "Accept: application/json"'
+    command << ' --show-error --fail' # Better diagnostics when the server returns an error
     command << " --url \"#{url}\""
     command
   end

data/lib/jirametrics/project_config.rb

@@ -58,7 +58,16 @@ class ProjectConfig
 
   def load_settings
     # This is the weird exception that we don't ever want mocked out so we skip FileSystem entirely.
-    JSON.parse(File.read(File.join(__dir__, 'settings.json'), encoding: 'UTF-8'))
+    settings = JSON.parse(File.read(File.join(__dir__, 'settings.json'), encoding: 'UTF-8'))
+
+    if settings['blocked_color']
+      file_system.deprecated message: 'blocked color should be set via css now', date: '2024-05-03'
+    end
+    if settings['stalled_color']
+      file_system.deprecated message: 'stalled color should be set via css now', date: '2024-05-03'
+    end
+
+    settings
   end
 
   def guess_project_id
@@ -295,8 +304,9 @@ class ProjectConfig
     file_system.foreach(@target_path) do |file|
       next unless file =~ /^#{get_file_prefix}_board_(\d+)_sprints_\d+.json$/
 
+      board_id = $1.to_i
       file_path = File.join(@target_path, file)
-      board = @all_boards[$1.to_i]
+      board = @all_boards[board_id]
       unless board
         @exporter.file_system.log(
           'Found sprint data but can\'t find a matching board in config. ' \
@@ -352,6 +362,12 @@ class ProjectConfig
     json.each { |user_data| @users << User.new(raw: user_data) }
   end
 
+  def atlassian_document_format
+    @atlassian_document_format ||= AtlassianDocumentFormat.new(
+      users: @users, timezone_offset: exporter.timezone_offset
+    )
+  end
+
   def to_time string, end_of_day: false
     time = end_of_day ? '23:59:59' : '00:00:00'
     string = "#{string}T#{time}#{exporter.timezone_offset}" if string.match?(/^\d{4}-\d{2}-\d{2}$/)
@@ -543,6 +559,7 @@ class ProjectConfig
   end
 
   def discard_changes_before status_becomes: nil, &block
+    cycletimes_touched = Set.new
     if status_becomes
       status_becomes = [status_becomes] unless status_becomes.is_a? Array
 
@@ -575,6 +592,7 @@ class ProjectConfig
       next if original_start_time.nil?
 
       issue.discard_changes_before cutoff_time
+      cycletimes_touched << issue.board.cycletime
 
       next unless cutoff_time
       next if original_start_time > cutoff_time # ie the cutoff would have made no difference.
@@ -585,5 +603,7 @@ class ProjectConfig
         issue: issue
       }
     end
+
+    cycletimes_touched.each { |c| c.flush_cache }
   end
 end

data/lib/jirametrics/raw_javascript.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# When strings are serialized into JSON, they're converted to actual strings. The purpose
+# of this class is to allow raw javascript to be passed through.
+class RawJavascript
+  def initialize content
+    @content = content
+  end
+
+  def to_json(*_args)
+    @content
+  end
+end

data/lib/jirametrics/settings.json

@@ -7,5 +7,7 @@
   "flagged_means_blocked": true,
 
   "expedited_priority_names": ["Critical", "Highest"],
-  "priority_order": ["Lowest", "Low", "Medium", "High", "Highest"]
+  "priority_order": ["Lowest", "Low", "Medium", "High", "Highest"],
+
+  "cache_cycletime_calculations": true
 }

data/lib/jirametrics/sprint.rb

@@ -13,6 +13,7 @@ class Sprint
   def id = @raw['id']
   def active? = (@raw['state'] == 'active')
   def closed? = (@raw['state'] == 'closed')
+  def future? = (@raw['state'] == 'future')
 
   def completed_at? time
     completed_at = completed_time
@@ -36,6 +37,17 @@ class Sprint
   def goal = @raw['goal']
   def name = @raw['name']
 
+  def day_count
+    return '' if future?
+
+    if closed?
+      days = (completed_time.to_date - start_time.to_date).to_i + 1
+    else
+      days = (end_time.to_date - start_time.to_date).to_i + 1
+    end
+    "#{days} days"
+  end
+
   private
 
   def parse_time time_string

data/lib/jirametrics/sprint_burndown.rb

@@ -48,8 +48,9 @@ class SprintBurndown < ChartBase
   end
 
   def run
-    sprints = sprints_in_time_range all_boards[board_id]
-    return nil if sprints.empty?
+    return nil unless current_board.scrum?
+
+    sprints = sprints_in_time_range current_board
 
     change_data_by_sprint = {}
     sprints.each do |sprint|
@@ -110,6 +111,9 @@ class SprintBurndown < ChartBase
 
   def sprints_in_time_range board
     board.sprints.select do |sprint|
+      # If it's never been started then it's just a holding area. Ignore it.
+      next if sprint.future?
+
       sprint_end_time = sprint.completed_time || sprint.end_time
       sprint_start_time = sprint.start_time
       next false if sprint_start_time.nil?