jirametrics 2.4 → 2.30

data/lib/jirametrics/cycle_time_config.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'jirametrics/self_or_issue_dispatcher'
+require 'date'
+
+class CycleTimeConfig
+  include SelfOrIssueDispatcher
+
+  attr_reader :label, :settings, :file_system
+
+  def initialize possible_statuses:, label:, block:, settings:, file_system: nil, today: Date.today
+    @possible_statuses = possible_statuses
+    @label = label
+    @today = today
+    @settings = settings
+
+    # If we hit something deprecated and this is nil then we'll blow up. Although it's ugly, this
+    # may make it easier to find problems in the test code ;-)
+    @file_system = file_system
+    instance_eval(&block) unless block.nil?
+  end
+
+  def start_at block = nil
+    @start_at = block unless block.nil?
+    @start_at
+  end
+
+  def stop_at block = nil
+    @stop_at = block unless block.nil?
+    @stop_at
+  end
+
+  def in_progress? issue
+    started_time, stopped_time = started_stopped_times(issue)
+    started_time && stopped_time.nil?
+  end
+
+  def done? issue
+    started_stopped_times(issue).last
+  end
+
+  def started_time issue
+    @file_system.deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
+    started_stopped_times(issue).first
+  end
+
+  def stopped_time issue
+    @file_system.deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
+    started_stopped_times(issue).last
+  end
+
+  def fabricate_change_item time
+    @file_system.deprecated(
+      date: '2024-12-16', message: "This method should now return a ChangeItem not a #{time.class}", depth: 4
+    )
+    raw = {
+      'field' => 'Fabricated change',
+      'to' => '0',
+      'toString' => '',
+      'from' => '0',
+      'fromString' => ''
+    }
+    ChangeItem.new raw: raw, time: time, artificial: true, author_raw: nil
+  end
+
+  def started_stopped_changes issue
+    cache_key = "#{issue.key}:#{issue.board.id}"
+    last_result = (@cache ||= {})[cache_key]
+    return *last_result if last_result && settings['cache_cycletime_calculations']
+
+    started = @start_at.call(issue)
+    stopped = @stop_at.call(issue)
+
+    # Obscure edge case where some of the start_at and stop_at blocks might return false in place of nil.
+    # If they are false then explicitly make them nil.
+    started ||= nil
+    stopped ||= nil
+
+    # These are only here for backwards compatibility. Hopefully nobody will ever need them.
+    started = fabricate_change_item(started) if !started.nil? && !started.is_a?(ChangeItem)
+    stopped = fabricate_change_item(stopped) if !stopped.nil? && !stopped.is_a?(ChangeItem)
+
+    # In the case where started and stopped are exactly the same time, we pretend that
+    # it just stopped and never started. This allows us to have logic like 'in or right of'
+    # for the start and not have it conflict.
+    started = nil if started&.time == stopped&.time
+
+    result = [started, stopped]
+    if last_result && result != last_result
+      @file_system.error(
+        "Calculation mismatch; this could break caching. #{issue.inspect} new=#{result.inspect}, " \
+          "previous=#{last_result.inspect}"
+      )
+    end
+    @cache[cache_key] = result
+    result
+  end
+
+  def started_stopped_times issue
+    started, stopped = started_stopped_changes(issue)
+    [started&.time, stopped&.time]
+  end
+
+  def flush_cache
+    @cache = nil
+  end
+
+  def started_stopped_dates issue
+    started_time, stopped_time = started_stopped_times(issue)
+    [started_time&.to_date, stopped_time&.to_date]
+  end
+
+  def cycletime issue
+    start, stop = started_stopped_times(issue)
+    return nil if start.nil? || stop.nil?
+
+    (stop.to_date - start.to_date).to_i + 1
+  end
+
+  def age issue, today: nil
+    start = started_stopped_times(issue).first
+    stop = today || @today || Date.today
+    return nil if start.nil? || stop.nil?
+
+    (stop.to_date - start.to_date).to_i + 1
+  end
+
+  def possible_statuses
+    if parent_config.is_a? BoardConfig
+      project_config = parent_config.project_config
+    else
+      # TODO: This will go away when cycletimes are no longer supported inside html_reports
+      project_config = parent_config.file_config.project_config
+    end
+    project_config.possible_statuses
+  end
+end

data/lib/jirametrics/cycletime_histogram.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
-require 'jirametrics/groupable_issue_chart'
+require 'jirametrics/time_based_histogram'
 
-class CycletimeHistogram < ChartBase
-  include GroupableIssueChart
+class CycletimeHistogram < TimeBasedHistogram
   attr_accessor :possible_statuses
 
   def initialize block
     super()
 
+    @x_axis_title = 'Cycletime in days'
+    @y_axis_title = 'Count'
+
     header_text 'Cycletime Histogram'
     description_text <<-HTML
       <p>
@@ -26,49 +28,26 @@ class CycletimeHistogram < ChartBase
     end
   end
 
-  def run
+  def all_items
     stopped_issues = completed_issues_in_range include_unstarted: true
 
     # For the histogram, we only want to consider items that have both a start and a stop time.
-    histogram_issues = stopped_issues.select { |issue| issue.board.cycletime.started_time(issue) }
-    rules_to_issues = group_issues histogram_issues
-
-    data_sets = rules_to_issues.keys.collect do |rules|
-      data_set_for(
-        histogram_data: histogram_data_for(issues: rules_to_issues[rules]),
-        label: rules.label,
-        color: rules.color
-      )
-    end
+    stopped_issues.select { |issue| issue.started_stopped_times.first }
+  end
 
-    wrap_and_render(binding, __FILE__)
+  def value_for_item issue
+    issue.board.cycletime.cycletime(issue)
   end
 
-  def histogram_data_for issues:
-    count_hash = {}
-    issues.each do |issue|
-      days = issue.board.cycletime.cycletime(issue)
-      count_hash[days] = (count_hash[days] || 0) + 1 if days.positive?
-    end
-    count_hash
+  def title_for_item count:, value:
+    "#{count} items completed in #{label_days value}"
   end
 
-  def data_set_for histogram_data:, label:, color:
-    keys = histogram_data.keys.sort
-    {
-      type: 'bar',
-      label: label,
-      data: keys.sort.filter_map do |key|
-        next if histogram_data[key].zero?
+  def sort_items items
+    items.sort_by(&:key_as_i)
+  end
 
-        {
-          x: key,
-          y: histogram_data[key],
-          title: "#{histogram_data[key]} items completed in #{label_days key}"
-        }
-      end,
-      backgroundColor: color,
-      borderRadius: 0
-    }
+  def label_for_item issue, hint:
+    "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
   end
 end

data/lib/jirametrics/cycletime_scatterplot.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
-require 'jirametrics/groupable_issue_chart'
-
-class CycletimeScatterplot < ChartBase
-  include GroupableIssueChart
+require 'jirametrics/time_based_scatterplot'
 
+class CycletimeScatterplot < TimeBasedScatterplot
   attr_accessor :possible_statuses
 
   def initialize block
@@ -24,8 +22,10 @@ class CycletimeScatterplot < ChartBase
         predict that most work of this type will complete in <%= overall_percent_line %> days or
         less. The other lines reflect the 85% line for that respective type of work.
       </div>
-      #{ describe_non_working_days }
+      #{describe_non_working_days}
     HTML
+    @x_axis_title = 'Date completed'
+    @y_axis_title = 'Cycletime in days'
 
     init_configuration_block block do
       grouping_rules do |issue, rule|
@@ -33,98 +33,29 @@ class CycletimeScatterplot < ChartBase
         rule.color = color_for type: issue.type
       end
     end
-
-    @percentage_lines = []
-    @highest_cycletime = 0
   end
 
-  def run
-    completed_issues = completed_issues_in_range include_unstarted: false
-
-    data_sets = create_datasets completed_issues
-    overall_percent_line = calculate_percent_line(completed_issues)
-    @percentage_lines << [overall_percent_line, CssVariable['--cycletime-scatterplot-overall-trendline-color']]
-
-    return "<h1>#{@header_text}</h1>No data matched the selected criteria. Nothing to show." if data_sets.empty?
-
-    wrap_and_render(binding, __FILE__)
+  def minimum_y_value
+    1 # Values under 1 day are data quality problems; they're flagged in the quality report instead
   end
 
-  def create_datasets completed_issues
-    data_sets = []
-
-    groups = group_issues completed_issues
-
-    groups.each_key do |rules|
-      completed_issues_by_type = groups[rules]
-      label = rules.label
-      color = rules.color
-      percent_line = calculate_percent_line completed_issues_by_type
-      data = completed_issues_by_type.filter_map { |issue| data_for_issue(issue) }
-      data_sets << {
-        label: "#{label} (85% at #{label_days(percent_line)})",
-        data: data,
-        fill: false,
-        showLine: false,
-        backgroundColor: color
-      }
-
-      data_sets << trend_line_data_set(label: label, data: data, color: color)
-
-      @percentage_lines << [percent_line, color]
-    end
-    data_sets
+  def all_items
+    completed_issues_in_range include_unstarted: false
   end
 
-  def show_trend_lines
-    @show_trend_lines = true
+  def x_value item
+    item.started_stopped_times.last
   end
 
-  def trend_line_data_set label:, data:, color:
-    points = data.collect do |hash|
-      [Time.parse(hash[:x]).to_i, hash[:y]]
-    end
-
-    # The trend calculation works with numbers only so convert Time to an int and back
-    calculator = TrendLineCalculator.new(points)
-    data_points = calculator.chart_datapoints(
-      range: time_range.begin.to_i..time_range.end.to_i,
-      max_y: @highest_cycletime
-    )
-    data_points.each do |point_hash|
-      point_hash[:x] = chart_format Time.at(point_hash[:x])
-    end
-
-    {
-      type: 'line',
-      label: "#{label} Trendline",
-      data: data_points,
-      fill: false,
-      borderWidth: 1,
-      markerType: 'none',
-      borderColor: color,
-      borderDash: [6, 3],
-      pointStyle: 'dash',
-      hidden: !@show_trend_lines
-    }
+  def y_value item
+    item.board.cycletime.cycletime(item)
   end
 
-  def data_for_issue issue
-    cycle_time = issue.board.cycletime.cycletime(issue)
-    return nil if cycle_time < 1 # These will get called out on the quality report
-
-    @highest_cycletime = cycle_time if @highest_cycletime < cycle_time
-
-    {
-      y: cycle_time,
-      x: chart_format(issue.board.cycletime.stopped_time(issue)),
-      title: ["#{issue.key} : #{issue.summary} (#{label_days(cycle_time)})"]
-    }
+  def title_value item, rules: nil
+    hint = @issue_hints&.fetch(item, nil)
+    "#{item.key} : #{item.summary} (#{label_days(y_value(item))})#{" #{hint}" if hint}"
   end
 
-  def calculate_percent_line completed_issues
-    times = completed_issues.collect { |issue| issue.board.cycletime.cycletime(issue) }
-    index = times.size * 85 / 100
-    times.sort[index]
-  end
+  # Kept for backwards compatibility with existing callers and specs
+  alias data_for_issue data_for_item
 end

data/lib/jirametrics/daily_view.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+class DailyView < ChartBase
+  attr_accessor :possible_statuses
+
+  def initialize _block
+    super()
+
+    header_text 'Daily View'
+    description_text <<-HTML
+      <div class="p">
+        This view shows all the items (<%= aging_issues.count %>) you'll want to discuss during your daily
+        coordination meeting
+        (aka daily scrum, standup), in the order that you should be discussing them. The most important
+        items are at the top, and the least at the bottom.
+      </div>
+      <div class="p">
+        By default, we sort by priority first and then by age within each of those priorities.
+        Hover over the issue to make it stand out more.
+      </div>
+    HTML
+  end
+
+  def run
+    aging_issues = select_aging_issues
+
+    return "<h1 class='foldable'>#{@header_text}</h1><div>There are no items currently in progress</div>" if aging_issues.empty?
+
+    result = +''
+    result << render_top_text(binding)
+    aging_issues.each do |issue|
+      result << render_issue(issue, child: false)
+    end
+    result
+  end
+
+  def select_aging_issues
+    aging_issues = issues.select do |issue|
+      started_at, stopped_at = issue.started_stopped_times
+      started_at && !stopped_at
+    end
+
+    today = date_range.end
+    aging_issues.collect do |issue|
+      [issue, issue.priority_name, issue.board.cycletime.age(issue, today: today)]
+    end.sort(&issue_sorter).collect(&:first)
+  end
+
+  def issue_sorter
+    priority_names = settings['priority_order']
+    lambda do |a, b|
+      a_issue, a_priority, a_age = *a
+      b_issue, b_priority, b_age = *b
+
+      a_priority_index = priority_names.index(a_priority)
+      b_priority_index = priority_names.index(b_priority)
+
+      if a_priority_index.nil? && b_priority_index.nil?
+        result = a_priority <=> b_priority
+      elsif a_priority_index.nil?
+        result = 1
+      elsif b_priority_index.nil?
+        result = -1
+      else
+        result = b_priority_index <=> a_priority_index
+      end
+
+      result = b_age <=> a_age if result.zero?
+      result = a_issue <=> b_issue if result.zero?
+      result
+    end
+  end
+
+  def make_blocked_stalled_lines issue
+    today = date_range.end
+    started_date = issue.started_stopped_times.first&.to_date
+    return [] unless started_date
+
+    blocked_stalled = issue.blocked_stalled_by_date(
+      date_range: today..today, chart_end_time: time_range.end, settings: settings
+    )[today]
+    return [] if blocked_stalled.active?
+
+    lines = []
+    if blocked_stalled.blocked?
+      marker = color_block '--blocked-color'
+      lines << ["#{marker} Blocked by flag"] if blocked_stalled.flag
+      lines << ["#{marker} Blocked by status: #{blocked_stalled.status}"] if blocked_stalled.blocked_by_status?
+      blocked_stalled.blocking_issue_keys&.each do |key|
+        blocking_issue = issues.find_by_key key: key, include_hidden: true
+        if blocking_issue
+          lines << "<section><div class=\"foldable startFolded\">#{marker} Blocked by issue: " \
+            "#{make_issue_label issue: blocking_issue, done: blocking_issue.done?}</div>"
+          lines << blocking_issue
+          lines << '</section>'
+        else
+          lines << ["#{marker} Blocked by issue: #{key} (no description found)"]
+        end
+      end
+    elsif blocked_stalled.stalled_by_status?
+      lines << ["#{color_block '--stalled-color'} Stalled by status: #{blocked_stalled.status}"]
+    else
+      lines << ["#{color_block '--stalled-color'} Stalled by inactivity: #{blocked_stalled.stalled_days} days"]
+    end
+    lines
+  end
+
+  def make_issue_label issue:, done:
+    label = "<img src='#{issue.type_icon_url}' title='#{issue.type}' class='icon' /> "
+    label << '<s>' if done
+    label << "<b><a href='#{issue.url}'>#{issue.key}</a></b> &nbsp;<i>#{issue.summary}</i>"
+    label << '</s>' if done
+    label
+  end
+
+  def make_title_line issue:, done:
+    title_line = +''
+    title_line << color_block('--expedited-color', title: 'Expedited') if issue.expedited?
+    title_line << make_issue_label(issue: issue, done: done)
+    title_line
+  end
+
+  def make_parent_lines issue
+    lines = []
+    parent_key = issue.parent_key
+    if parent_key
+      parent = issues.find_by_key key: parent_key, include_hidden: true
+      text = parent ? make_issue_label(issue: parent, done: parent.done?) : parent_key
+      lines << ["Parent: #{text}"]
+    end
+    lines
+  end
+
+  def make_stats_lines issue:, done:
+    line = []
+
+    line << "<img src='#{issue.priority_url}' class='icon' /> <b>#{issue.priority_name}</b>"
+
+    if done
+      cycletime = issue.board.cycletime.cycletime(issue)
+
+      line << "Cycletime: <b>#{label_days cycletime}</b>"
+    else
+      age = issue.board.cycletime.age(issue, today: date_range.end)
+      line << "Age: <b>#{age ? label_days(age) : '(Not Started)'}</b>"
+    end
+    line << "Status: <b>#{format_status issue.status, board: issue.board}</b>"
+
+    column = issue.board.visible_columns.find { |c| c.status_ids.include?(issue.status.id) }
+    line << "Column: <b>#{column&.name || '(not visible on board)'}</b>"
+
+    if issue.assigned_to
+      line << "Assignee: <img src='#{issue.assigned_to_icon_url}' class='icon' /> <b>#{issue.assigned_to}</b>"
+    end
+
+    if issue.due_date
+      today = date_range.end
+      days = (issue.due_date - today).to_i
+      relative =
+        if days.zero? then 'today'
+        elsif days.positive? then "in #{label_days days}"
+        else "#{label_days(-days)} ago"
+        end
+      content = "#{issue.due_date} (#{relative})"
+      content = "<span style='background: var(--warning-banner)'>#{content}</span>" if days.negative?
+      line << "Due: <b>#{content}</b>"
+    end
+
+    block = lambda do |collection, label|
+      unless collection.empty?
+        text = collection.collect { |l| "<span class='label'>#{l}</span>" }.join(' ')
+        line << "#{label} #{text}"
+      end
+    end
+    block.call issue.labels, 'Labels:'
+    block.call issue.component_names, 'Components:'
+
+    [line]
+  end
+
+  def make_child_lines issue
+    lines = []
+    subtasks = issue.subtasks
+
+    return lines if subtasks.empty?
+
+    lines << "<section><div class=\"foldable startFolded\">Child issues (#{subtasks.count})</div>"
+    lines += subtasks
+    lines << '</section>'
+
+    lines
+  end
+
+  def make_history_lines issue
+    history = issue.changes.reverse
+    lines = []
+
+    lines << '<section><div class="foldable startFolded">Issue history</div>'
+    table = +''
+    table << '<table>'
+    history.each do |c|
+      time = c.time.strftime '%b %d, %Y @ %I:%M%P'
+
+      table << '<tr>'
+      table << "<td><span class='time' title='Timestamp: #{c.time}'>#{time}</span></td>"
+      table << "<td><img src='#{c.author_icon_url}' class='icon' title='#{c.author}' /></td>"
+      text = history_text change: c, board: issue.board
+      table << "<td><span class='field'>#{c.field_as_human_readable}</span> #{text}</td>"
+      table << '</tr>'
+    end
+    table << '</table>'
+    lines << [table]
+    lines << '</section>'
+    lines
+  end
+
+  def history_text change:, board:
+    convertor = ->(value, _id) { value.inspect }
+    convertor = ->(_value, id) { format_status(board.possible_statuses.find_by_id(id), board: board) } if change.status?
+
+    if change.comment? || change.description?
+      atlassian_document_format.to_html(change.value)
+    elsif %w[status priority assignee duedate issuetype].include?(change.field)
+      to = convertor.call(change.value, change.value_id)
+      if change.old_value
+        from = convertor.call(change.old_value, change.old_value_id)
+        "Changed from #{from} to #{to}"
+      else
+        "Set to #{to}"
+      end
+    elsif change.flagged?
+      change.value == '' ? 'Off' : 'On'
+    else
+      change.value
+    end
+  end
+
+  def make_sprints_lines issue
+    return [] unless issue.board.scrum?
+
+    sprint_names = issue.sprints.collect do |sprint|
+      if sprint.closed?
+        "<s>#{sprint.name}</s>"
+      else
+        sprint.name
+      end
+    end
+
+    return [['Sprints: NONE']] if sprint_names.empty?
+
+    [[+'Sprints: ' << sprint_names
+      .collect { |name| "<span class='label'>#{name}</span>" }
+      .join(' ')]]
+  end
+
+  def make_description_lines issue
+    description = issue.raw['fields']['description']
+    return [] unless description
+
+    text = "<div class='foldable startFolded'>Description</div>" \
+           "<div>#{atlassian_document_format.to_html(description)}</div>"
+    [[text]]
+  end
+
+  def assemble_issue_lines issue, child:
+    done = issue.done?
+
+    lines = []
+    lines << [make_title_line(issue: issue, done: done)]
+    lines << make_not_visible_line(issue)
+    lines += make_parent_lines(issue) unless child
+    lines += make_stats_lines(issue: issue, done: done)
+    unless done
+      lines += make_description_lines(issue)
+      lines += make_sprints_lines(issue)
+      lines += make_blocked_stalled_lines(issue)
+      lines += make_child_lines(issue)
+      lines += make_history_lines(issue)
+    end
+    lines.compact
+  end
+
+  def render_issue issue, child:
+    css_class = child ? 'child_issue' : 'daily_issue'
+    result = +''
+    result << "<div class='#{css_class}'>"
+    assemble_issue_lines(issue, child: child).each do |row|
+      if row.is_a? Issue
+        result << render_issue(row, child: true)
+      elsif row.is_a?(String)
+        result << row
+      else
+        result << '<div class="heading">'
+        row.each do |chunk|
+          result << "<div>#{chunk}</div>"
+        end
+        result << '</div>'
+      end
+    end
+    result << '</div>'
+  end
+
+  def make_not_visible_line issue
+    not_visible_text issue
+  end
+end

data/lib/jirametrics/daily_wip_by_age_chart.rb

@@ -4,7 +4,7 @@ require 'jirametrics/daily_wip_chart'
 
 class DailyWipByAgeChart < DailyWipChart
   def initialize block
-    super(block)
+    super
 
     add_trend_line line_color: '--aging-work-in-progress-by-age-trend-line-color', group_labels: [
       'Less than a day',
@@ -49,11 +49,7 @@ class DailyWipByAgeChart < DailyWipChart
   end
 
   def default_grouping_rules issue:, rules:
-    cycletime = issue.board.cycletime
-    started = cycletime.started_time(issue)&.to_date
-    stopped = cycletime.stopped_time(issue)&.to_date
-
-    rules.issue_hint = "(age: #{label_days (rules.current_date - started + 1).to_i})" if started
+    started, stopped = issue.started_stopped_dates
 
     if stopped && started.nil? # We can't tell when it started
       @has_completed_but_not_started = true
@@ -74,7 +70,7 @@ class DailyWipByAgeChart < DailyWipChart
       rules.label = 'Start date unknown'
       rules.color = '--body-background'
       rules.group_priority = 11
-      created_days = rules.current_date - created + 1
+      created_days = rules.current_date - created
       rules.issue_hint = "(created: #{label_days created_days.to_i} earlier, stopped on #{stopped})"
     end
   end
@@ -86,7 +82,8 @@ class DailyWipByAgeChart < DailyWipChart
   end
 
   def group_by_age started:, rules:
-    age = rules.current_date - started + 1
+    age = (rules.current_date - started).to_i + 1
+    rules.issue_hint = "(age: #{label_days age})"
 
     case age
     when 1