jirametrics 2.22 → 2.30

data/lib/jirametrics/html_report_config.rb

@@ -20,33 +20,58 @@ class HtmlReportConfig < HtmlGenerator
     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: 'flow_efficiency_scatterplot', classname: 'FlowEfficiencyScatterplot'
-  define_chart name: 'daily_view', classname: 'DailyView'
-
   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:
+    super()
     @file_config = file_config
     @block = block
     @sections = [] # Where we store the chunks of text that will be assembled into the HTML
     @charts = [] # Where we store all the charts we executed so we can assert against them.
   end
 
+  def method_missing name, *_args, board_id: nil, **_kwargs, &block
+    class_name = name.to_s.split('_').map(&:capitalize).join
+    klass = resolve_chart_class(class_name)
+    return super if klass.nil?
+
+    block ||= ->(_) {}
+
+    if klass.instance_method(:board_id=).owner == klass
+      execute_chart_per_board klass: klass, block: block, board_id: board_id
+    else
+      execute_chart klass.new(block)
+    end
+  end
+
+  def resolve_chart_class class_name
+    klass = Object.const_get(class_name)
+    klass < ChartBase ? klass : nil
+  rescue NameError
+    nil
+  end
+
+  def execute_chart_per_board klass:, block:, board_id:
+    all_boards = @file_config.project_config.all_boards
+    ids = board_id ? [board_id] : issues.collect { |i| i.board.id }.uniq
+    ids = ids.sort_by { |id| all_boards[id]&.name || '' }
+    ids.each_with_index do |id, index|
+      execute_chart(klass.new(block)) do |chart|
+        chart.board_id = id
+        # We're showing the description only on the first one in order to reduce noise on the report
+        chart.description_text nil unless index.zero?
+      end
+    end
+  end
+
+  def respond_to_missing? name, include_private = false
+    class_name = name.to_s.split('_').map(&:capitalize).join
+    !resolve_chart_class(class_name).nil? || super
+  end
+
   def cycletime label = nil, &block
     @file_config.project_config.all_boards.each_value do |board|
       raise 'Multiple cycletimes not supported' if board.cycletime
@@ -73,7 +98,8 @@ class HtmlReportConfig < HtmlGenerator
 
     html create_footer
 
-    create_html output_filename: @file_config.output_filename, settings: settings
+    create_html output_filename: @file_config.output_filename, settings: settings,
+                project_name: @file_config.project_config.name
   end
 
   def file_system
@@ -92,24 +118,9 @@ class HtmlReportConfig < HtmlGenerator
     @file_config.project_config.exporter.timezone_offset
   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
-      ids = [board_id]
-    end
-
-    ids.each do |id|
-      execute_chart(AgingWorkInProgressChart.new(block)) do |chart|
-        chart.board_id = id
-      end
-    end
-  end
-
   def random_color
-    "##{Random.bytes(3).unpack1('H*')}"
+    @palette_index = (@palette_index || -1) + 1
+    ChartBase::OKABE_ITO_PALETTE[@palette_index % ChartBase::OKABE_ITO_PALETTE.size]
   end
 
   def html string, type: :body
@@ -147,6 +158,7 @@ class HtmlReportConfig < HtmlGenerator
     chart.all_boards = project_config.all_boards
     chart.board_id = find_board_id
     chart.holiday_dates = project_config.exporter.holiday_dates
+    chart.fix_versions = project_config.fix_versions
 
     time_range = @file_config.project_config.time_range
     chart.date_range = time_range.begin.to_date..time_range.end.to_date

data/lib/jirametrics/issue.rb

@@ -3,14 +3,15 @@
 require 'time'
 
 class Issue
-  attr_reader :changes, :raw, :subtasks, :board
-  attr_accessor :parent
+  attr_reader :changes, :raw, :subtasks, :board, :discarded_changes, :discarded_change_times
+  attr_accessor :parent, :github_prs
 
   def initialize raw:, board:, timezone_offset: '+00:00'
     @raw = raw
     @timezone_offset = timezone_offset
     @subtasks = []
     @changes = []
+    @github_prs = []
     @board = board
 
     # We only check for this here because if a board isn't passed in then things will fail much
@@ -47,8 +48,8 @@ class Issue
   def type = @raw['fields']['issuetype']['name']
   def type_icon_url = @raw['fields']['issuetype']['iconUrl']
 
-  def priority_name = @raw['fields']['priority']['name']
-  def priority_url = @raw['fields']['priority']['iconUrl']
+  def priority_name = @raw.dig('fields', 'priority', 'name')
+  def priority_url = @raw.dig('fields', 'priority', 'iconUrl')
 
   def summary = @raw['fields']['summary']
 
@@ -209,7 +210,38 @@ class Issue
   end
 
   def first_time_visible_on_board
-    first_time_in_status(*board.visible_columns.collect(&:status_ids).flatten)
+    visible_status_ids = board.visible_columns.collect(&:status_ids).flatten
+    return first_time_in_status(*visible_status_ids) unless board.scrum?
+
+    # For scrum boards, an issue is only visible when BOTH conditions are true simultaneously:
+    # 1. Its status is in a visible column
+    # 2. It is in an active sprint
+    # At each moment one condition becomes true, check if the other is already true.
+    candidates = []
+
+    status_changes.each do |change|
+      next unless visible_status_ids.include?(change.value_id)
+      candidates << change if in_active_sprint_at?(change.time)
+    end
+
+    sprint_entry_events.each do |effective_time, representative_change|
+      candidates << representative_change if in_visible_status_at?(effective_time, visible_status_ids)
+    end
+
+    candidates.min_by(&:time)
+  end
+
+  def reasons_not_visible_on_board
+    reasons = []
+    reasons << 'Not in an active sprint' if board.scrum? && sprints.none?(&:active?)
+    unless board.visible_columns.any? { |c| c.status_ids.include?(status.id) }
+      reasons << 'Status is not configured for any visible column on the board'
+    end
+    reasons
+  end
+
+  def visible_on_board?
+    reasons_not_visible_on_board.empty?
   end
 
   # If this issue will ever be in an active sprint then return the time that it
@@ -270,13 +302,19 @@ class Issue
     # 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
+    if sprint
+      return [nil, nil] if sprint.future?
+
+      return [sprint.start_time, sprint.completed_time]
+    end
 
     # 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
+      return [nil, nil] if sprint_data['state'] == 'future'
+
       start = parse_time(sprint_data['startDate'])
       stop = parse_time(sprint_data['completeDate'])
       return [start, stop]
@@ -388,21 +426,11 @@ class Issue
     results
   end
 
-  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)
-      raise "blocked_statuses(#{blocked_statuses.inspect}) and " \
-        "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_statuses = settings['blocked_statuses']
+    stalled_statuses = settings['stalled_statuses']
 
     blocked_link_texts = settings['blocked_link_text']
     stalled_threshold = settings['stalled_threshold_days']
@@ -415,7 +443,9 @@ class Issue
     previous_change_time = created
 
     blocking_status = nil
+    blocking_is_blocked = false
     flag = nil
+    flag_reason = nil
 
     # This mock change is to force the writing of one last entry at the end of the time range.
     # By doing this, we're able to eliminate a lot of duplicated code in charts.
@@ -430,11 +460,14 @@ class Issue
       )
 
       if change.flagged? && flagged_means_blocked
-        flag = change.value
-        flag = nil if change.value == ''
+        flag, flag_reason = blocked_stalled_changes_flag_logic change
       elsif change.status?
         blocking_status = nil
-        if blocked_statuses.include?(change.value) || stalled_statuses.include?(change.value)
+        blocking_is_blocked = false
+        if blocked_statuses.find_by_id(change.value_id)
+          blocking_status = change.value
+          blocking_is_blocked = true
+        elsif stalled_statuses.find_by_id(change.value_id)
           blocking_status = change.value
         end
       elsif change.link?
@@ -455,8 +488,9 @@ class Issue
 
       new_change = BlockedStalledChange.new(
         flagged: flag,
+        flag_reason: flag_reason,
         status: blocking_status,
-        status_is_blocking: blocking_status.nil? || blocked_statuses.include?(blocking_status),
+        status_is_blocking: blocking_status.nil? || blocking_is_blocked,
         blocking_issue_keys: (blocking_issue_keys.empty? ? nil : blocking_issue_keys.dup),
         time: change.time
       )
@@ -475,6 +509,7 @@ class Issue
       hack = result.pop
       result << BlockedStalledChange.new(
         flagged: hack.flag,
+        flag_reason: hack.flag_reason,
         status: hack.status,
         status_is_blocking: hack.status_is_blocking,
         blocking_issue_keys: hack.blocking_issue_keys,
@@ -486,6 +521,28 @@ class Issue
     result
   end
 
+  def blocked_stalled_changes_flag_logic change
+    flag = change.value
+    flag = nil if change.value == ''
+    if flag
+      # When the user is adding a comment to explain why a flag was set, the flag is set immediately
+      # and the comment is inserted after the user hits enter, which means that there is some time
+      # gap. If a comment happened shortly after the flag was set, we assume they're linked. This
+      # won't always be true and so there will be false positives, but it's a reasonable assumption.
+      max_seconds_between_flag_and_comment = 30
+      comment_change = changes.find do |c|
+        c.comment? && c.time >= change.time && (c.time - change.time) <= max_seconds_between_flag_and_comment
+      end
+      flag_reason = comment_change && @board.project_config.atlassian_document_format.to_text(comment_change.value)
+      # Newer Jira instances may add this extra text but older instances did not. Strip it out if found.
+      flag_reason = flag_reason&.sub(/\A:flag_on: Flag added\s*/m, '')&.strip
+      flag_reason = nil if flag_reason&.empty?
+    else
+      flag_reason = nil
+    end
+    [flag, flag_reason]
+  end
+
   def check_for_stalled change_time:, previous_change_time:, stalled_threshold:, blocking_stalled_changes:
     stalled_threshold_seconds = stalled_threshold * 60 * 60 * 24
 
@@ -521,7 +578,7 @@ class Issue
   # return [number of active seconds, total seconds] that this issue had up to the end_time.
   # It does not include data before issue start or after issue end
   def flow_efficiency_numbers end_time:, settings: @board.project_config.settings
-    issue_start, issue_stop = @board.cycletime.started_stopped_times(self)
+    issue_start, issue_stop = started_stopped_times
     return [0.0, 0.0] if !issue_start || issue_start > end_time
 
     value_add_time = 0.0
@@ -701,75 +758,7 @@ class Issue
   end
 
   def dump
-    result = +''
-    result << "#{key} (#{type}): #{compact_text summary, max: 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
-    history = [] # time, type, detail
-
-    if board.cycletime
-      started_at, stopped_at = board.cycletime.started_stopped_times(self)
-      history << [started_at, nil, '↓↓↓↓ Started here ↓↓↓↓', true] if started_at
-      history << [stopped_at, nil, '↑↑↑↑ Finished here ↑↑↑↑', true] if stopped_at
-    else
-      result << "  Unable to determine start/end times as board #{board.id} has no cycletime specified\n"
-    end
-
-    @discarded_change_times&.each do |time|
-      history << [time, nil, '↑↑↑↑ Changes discarded ↑↑↑↑', true]
-    end
-
-    (changes + (@discarded_changes || [])).each do |change|
-      if change.status?
-        value = "#{change.value.inspect}:#{change.value_id.inspect}"
-        old_value = change.old_value ? "#{change.old_value.inspect}:#{change.old_value_id.inspect}" : nil
-      else
-        value = compact_text(change.value).inspect
-        old_value = change.old_value ? compact_text(change.old_value).inspect : nil
-      end
-
-      message = +''
-      message << "#{old_value} -> " unless old_value.nil? || old_value.empty?
-      message << value
-      if change.artificial?
-        message << ' (Artificial entry)' if change.artificial?
-      else
-        message << " (Author: #{change.author})"
-      end
-      history << [change.time, change.field, message, change.artificial?]
-    end
-
-    result << "  History:\n"
-    type_width = history.collect { |_time, type, _detail, _artificial| type&.length || 0 }.max
-    history.sort! do |a, b|
-      if a[0] == b[0]
-        if a[1].nil?
-          1
-        elsif b[1].nil?
-          -1
-        else
-          a[1] <=> b[1]
-        end
-      else
-        a[0] <=> b[0]
-      end
-    end
-    history.each do |time, type, detail, _artificial|
-      if type.nil?
-        type = '-' * type_width
-      else
-        type = (' ' * (type_width - type.length)) << type
-      end
-      result << "    #{time.strftime '%Y-%m-%d %H:%M:%S %z'} [#{type}] #{detail}\n"
-    end
-
-    result
+    IssuePrinter.new(self).to_s
   end
 
   def done?
@@ -782,10 +771,36 @@ class Issue
     end
   end
 
+  def started_stopped_times
+    board.cycletime.started_stopped_times(self)
+  end
+
+  def started_stopped_dates
+    board.cycletime.started_stopped_dates(self)
+  end
+
   def status_changes
     @changes.select { |change| change.status? }
   end
 
+  def status_resolution_at_done
+    done_time = started_stopped_times.last
+    return [nil, nil] if done_time.nil?
+
+    status_change = nil
+    resolution = nil
+
+    @changes.each do |change|
+      break if change.time > done_time
+
+      status_change = change if change.status?
+      resolution = change.value if change.resolution?
+    end
+
+    status = status_change ? find_or_create_status(id: status_change.value_id, name: status_change.value) : nil
+    [status, resolution]
+  end
+
   def sprints
     sprint_ids = []
 
@@ -806,23 +821,106 @@ class Issue
   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 = if text.is_a? Hash
+             @board.project_config.atlassian_document_format.to_text(text)
+           else
+             text
+           end
+    text = text.gsub(/\s+/, ' ').strip
+    text = "#{text[0...max]}..." if text.length > max
     text
   end
 
   private
 
+  # Returns [[effective_time, change_item]] for each moment the issue entered an active sprint.
+  # Skips sprints that were removed before they activated.
+  def sprint_entry_events
+    data_clazz = Struct.new(:sprint_id, :sprint_start, :add_time, :change)
+    events = []
+    in_sprint = []
+
+    @changes.each do |change|
+      next unless change.sprint?
+
+      (change.value_id - change.old_value_id).each do |sprint_id|
+        sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
+        in_sprint << data_clazz.new(sprint_id, sprint_start, change.time, change) if sprint_start
+      end
+
+      (change.old_value_id - change.value_id).each do |sprint_id|
+        data = in_sprint.find { |d| d.sprint_id == sprint_id }
+        next unless data
+
+        in_sprint.delete(data)
+        next if data.sprint_start >= change.time # sprint hadn't activated before removal
+
+        effective_time = [data.add_time, data.sprint_start].max
+        events << [effective_time, sprint_change_at(effective_time, data.change)]
+      end
+    end
+
+    in_sprint.each do |data|
+      effective_time = [data.add_time, data.sprint_start].max
+      events << [effective_time, sprint_change_at(effective_time, data.change)]
+    end
+
+    events
+  end
+
+  def sprint_change_at effective_time, change
+    return change if effective_time == change.time
+
+    ChangeItem.new(
+      raw: { 'field' => 'Sprint', 'toString' => 'Sprint activated', 'to' => '0', 'from' => nil, 'fromString' => nil },
+      author_raw: nil,
+      time: effective_time,
+      artificial: true
+    )
+  end
+
+  def in_active_sprint_at? time
+    active_ids = []
+    @changes.each do |change|
+      break if change.time > time
+      next unless change.sprint?
+
+      (change.value_id - change.old_value_id).each do |sprint_id|
+        sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
+        active_ids << sprint_id if sprint_start && sprint_start <= time
+      end
+      (change.old_value_id - change.value_id).each { |id| active_ids.delete(id) }
+    end
+    active_ids.any?
+  end
+
+  def in_visible_status_at? time, visible_status_ids
+    last = status_changes.reverse.find { |c| c.time <= time }
+    last && visible_status_ids.include?(last.value_id)
+  end
+
   def load_history_into_changes
     @raw['changelog']['histories']&.each do |history|
       created = parse_time(history['created'])
 
       history['items']&.each do |item|
+        if item['field'] == 'status' && item['to'].nil?
+          to_name = item['toString']
+          matches = board.possible_statuses.find_all_by_name(to_name)
+          guessed_id, id_note = if matches.length == 1
+            [matches.first.id.to_s, "Guessed id #{matches.first.id} from status name."]
+          elsif matches.length > 1
+            ['0', "Multiple statuses named #{to_name.inspect} exist (ids: #{matches.map(&:id).join(', ')}); cannot disambiguate. Using id 0."]
+          else
+            ['0', "No known status named #{to_name.inspect}. Using id 0."]
+          end
+          board.project_config.file_system.warning(
+            "Issue #{key} has a status change without a 'to' id " \
+            "(from #{item['fromString'].inspect} to #{to_name.inspect}). #{id_note}"
+          )
+          item = item.merge('to' => guessed_id)
+        end
+
         @changes << ChangeItem.new(raw: item, time: created, author_raw: history['author'])
       end
     end

data/lib/jirametrics/issue_printer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+class IssuePrinter
+  def initialize issue
+    @issue = issue
+  end
+
+  def to_s
+    issue = @issue
+    result = +''
+    result << "#{issue.key} (#{issue.type}): #{issue.compact_text issue.summary, max: 200}\n"
+
+    assignee = issue.raw['fields']['assignee']
+    result << "  [assignee] #{assignee['name'].inspect} <#{assignee['emailAddress']}>\n" unless assignee.nil?
+
+    issue.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
+
+    history = [] # time, type, detail
+
+    if issue.board.cycletime
+      started_at, stopped_at = issue.started_stopped_times
+      history << [started_at, nil, 'vvvv Started here vvvv', true] if started_at
+      history << [stopped_at, nil, '^^^^ Finished here ^^^^', true] if stopped_at
+    else
+      result << "  Unable to determine start/end times as board #{issue.board.id} has no cycletime specified\n"
+    end
+
+    issue.discarded_change_times&.each do |time|
+      history << [time, nil, '^^^^ Changes discarded ^^^^', true]
+    end
+
+    (issue.changes + (issue.discarded_changes || [])).each do |change|
+      history << [change.time, change.field, create_change_message(change: change, issue: issue), change.artificial?]
+    end
+
+    result << "  History:\n"
+    type_width = history.collect { |_time, type, _detail, _artificial| type&.length || 0 }.max
+    sort_history!(history)
+    history.each do |time, type, detail, _artificial|
+      type = type.nil? ? '-' * type_width : type.rjust(type_width)
+      result << "    #{time.strftime '%Y-%m-%d %H:%M:%S %z'} [#{type}] #{detail}\n"
+    end
+
+    result
+  end
+
+  def create_change_message change:, issue:
+    value, old_value = format_change_values(change: change, issue: issue)
+
+    message = +''
+    message << "#{old_value} -> " unless old_value.nil? || old_value.empty?
+    message << value
+    if change.artificial?
+      message << ' (Artificial entry)'
+    else
+      message << " (Author: #{change.author})"
+    end
+    message
+  end
+
+  def format_change_values change:, issue:
+    if change.status?
+      value = "#{change.value.inspect}:#{change.value_id.inspect}"
+      old_value = change.old_value ? "#{change.old_value.inspect}:#{change.old_value_id.inspect}" : nil
+    elsif change.sprint?
+      added = change.value_id - change.old_value_id
+      removed = change.old_value_id - change.value_id
+      value = "#{change.value.inspect} #{change.value_id}"
+      value << " (added: #{added})" unless added.empty?
+      value << " (removed: #{removed})" unless removed.empty?
+      old_value = nil
+    else
+      value = issue.compact_text(change.value).inspect
+      old_value = change.old_value ? issue.compact_text(change.old_value).inspect : nil
+    end
+    [value, old_value]
+  end
+
+  def sort_history! history
+    history.sort! do |a, b|
+      if a[0] == b[0]
+        if a[1].nil?
+          1
+        elsif b[1].nil?
+          -1
+        else
+          a[1] <=> b[1]
+        end
+      else
+        a[0] <=> b[0]
+      end
+    end
+  end
+end