jirametrics 2.4 → 2.11

data/lib/jirametrics/board_movement_calculator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+class BoardMovementCalculator
+  attr_reader :board, :issues, :today
+
+  def initialize board:, issues:, today:
+    @board = board
+    @issues = issues.select { |issue| issue.board == board && issue.done? && !moves_backwards?(issue) }
+    @today = today
+  end
+
+  def moves_backwards? issue
+    started, stopped = issue.board.cycletime.started_stopped_times(issue)
+    return false unless started
+
+    previous_column = nil
+    issue.status_changes.each do |change|
+      column = board.visible_columns.index { |c| c.status_ids.include?(change.value_id) }
+      next if change.time < started
+      next if column.nil? # It disappeared from the board for a bit
+      return true if previous_column && column && column < previous_column
+
+      previous_column = column
+    end
+    false
+  end
+
+  def stacked_age_data_for percentages:
+    data_list = percentages.sort.collect do |percentage|
+      [percentage, age_data_for(percentage: percentage)]
+    end
+
+    stack_data data_list
+  end
+
+  def stack_data data_list
+    remainder = nil
+    data_list.collect do |percentage, data|
+      unless remainder.nil?
+        data = (0...data.length).collect do |i|
+          data[i] - remainder[i]
+        end
+
+      end
+      remainder = data
+
+      [percentage, data]
+    end
+  end
+
+  def age_data_for percentage:
+    data = []
+    board.visible_columns.each_with_index do |_column, column_index|
+      ages = ages_of_issues_when_leaving_column column_index: column_index, today: today
+
+      if ages.empty?
+        data << 0
+      else
+        index = ((ages.size - 1) * percentage / 100).to_i
+        data << ages[index]
+      end
+    end
+    data
+  end
+
+  def ages_of_issues_when_leaving_column column_index:, today:
+    this_column = board.visible_columns[column_index]
+    next_column = board.visible_columns[column_index + 1]
+
+    @issues.filter_map do |issue|
+      this_column_start = issue.first_time_in_or_right_of_column(this_column.name)&.time
+      next_column_start = next_column.nil? ? nil : issue.first_time_in_or_right_of_column(next_column.name)&.time
+      issue_start, issue_done = issue.board.cycletime.started_stopped_times(issue)
+
+      # Skip if we can't tell when it started.
+      next if issue_start.nil?
+
+      # Skip if it never entered this column
+      next if this_column_start.nil?
+
+      # Skip if it left this column before the item is considered started.
+      next 0 if next_column_start && next_column_start <= issue_start
+
+      # Skip if it was already done by the time it got to this column or it became done when it got to this column
+      next if issue_done && issue_done <= this_column_start
+
+      end_date = case # rubocop:disable Style/EmptyCaseCondition
+      when next_column_start.nil?
+        # If this is the last column then base age against today
+        today
+      when issue_done && issue_done < next_column_start
+        # it completed while in this column
+        issue_done.to_date
+      else
+        # It passed through this whole column
+        next_column_start.to_date
+      end
+      (end_date - issue_start.to_date).to_i + 1
+    end.sort
+  end
+
+  # Figure out what column this is issue is currently in and what time it entered that column. We need this for
+  # aging and forecasting purposes
+  def find_current_column_and_entry_time_in_column issue
+    column = board.visible_columns.find { |c| c.status_ids.include?(issue.status.id) }
+    return [] if column.nil? # This issue isn't visible on the board
+
+    status_ids = column.status_ids
+
+    entry_at = issue.changes.reverse.find { |change| change.status? && status_ids.include?(change.value_id) }&.time
+
+    [column.name, entry_at]
+  end
+
+  def label_days days
+    "#{days} day#{'s' unless days == 1}"
+  end
+
+  def forecasted_days_remaining_and_message issue:, today:
+    return [nil, 'Already done'] if issue.done?
+
+    likely_age_data = age_data_for percentage: 85
+
+    column_name, entry_time = find_current_column_and_entry_time_in_column issue
+    return [nil, 'This issue is not visible on the board. No way to predict when it will be done.'] if column_name.nil?
+
+    age_in_column = (today - entry_time.to_date).to_i + 1
+
+    message = nil
+    column_index = board.visible_columns.index { |c| c.name == column_name }
+
+    last_non_zero_datapoint = likely_age_data.reverse.find { |d| !d.zero? }
+    return [nil, 'There is no historical data for this board. No forecast can be made.'] if last_non_zero_datapoint.nil?
+
+    remaining_in_current_column = likely_age_data[column_index] - age_in_column
+    if remaining_in_current_column.negative?
+      message = "This item is an outlier at #{label_days issue.board.cycletime.age(issue, today: today)} " \
+        "in the #{column_name.inspect} column. Most items on this board have left this column in " \
+        "#{label_days likely_age_data[column_index]} or less, so we cannot forecast when it will be done."
+      remaining_in_current_column = 0
+      return [nil, message]
+    end
+
+    forecasted_days = last_non_zero_datapoint - likely_age_data[column_index] + remaining_in_current_column
+    [forecasted_days, message]
+  end
+end

data/lib/jirametrics/change_item.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 class ChangeItem
-  attr_reader :field, :value_id, :old_value_id, :raw, :author
-  attr_accessor :value, :old_value, :time
+  attr_reader :field, :value_id, :old_value_id, :raw, :author, :time
+  attr_accessor :value, :old_value
 
   def initialize raw:, time:, author:, artificial: false
     @raw = raw
     @time = time
-    raise "Time must be an object of type Time in the correct timezone: #{@time}" if @time.is_a? String
+    raise 'ChangeItem.new() time cannot be nil' if time.nil?
+    raise "Time must be an object of type Time in the correct timezone: #{@time.inspect}" unless @time.is_a? Time
 
-    @field = field || @raw['field']
-    @value = value || @raw['toString']
+    @field = @raw['field']
+    @value = @raw['toString']
     @value_id = @raw['to'].to_i
     @old_value = @raw['fromString']
     @old_value_id = @raw['from']&.to_i
@@ -34,9 +35,21 @@ class ChangeItem
 
   def link? = (field == 'Link')
 
+  def labels? = (field == 'labels')
+
+  # An alias for time so that logic accepting a Time, Date, or ChangeItem can all respond to :to_time
+  def to_time = @time
+
   def to_s
     message = +''
-    message << "ChangeItem(field: #{field.inspect}, value: #{value.inspect}, time: #{time_to_s(@time).inspect}"
+    message << "ChangeItem(field: #{field.inspect}"
+    message << ", value: #{value.inspect}"
+    message << ':' << value_id.inspect if status?
+    if old_value
+      message << ", old_value: #{old_value.inspect}"
+      message << ':' << old_value_id.inspect if status?
+    end
+    message << ", time: #{time_to_s(@time).inspect}"
     message << ', artificial' if artificial?
     message << ')'
     message

data/lib/jirametrics/chart_base.rb

@@ -25,6 +25,11 @@ class ChartBase
     @aggregated_project
   end
 
+  def html_directory
+    pathname = Pathname.new(File.realpath(__FILE__))
+    "#{pathname.dirname}/html"
+  end
+
   def render caller_binding, file
     pathname = Pathname.new(File.realpath(file))
     basename = pathname.basename.to_s
@@ -33,8 +38,8 @@ class ChartBase
     # Insert a incrementing chart_id so that all the chart names on the page are unique
     caller_binding.eval "chart_id='chart#{next_id}'" # chart_id=chart3
 
-    @html_directory = "#{pathname.dirname}/html"
-    erb = ERB.new file_system.load "#{@html_directory}/#{$1}.erb"
+    # @html_directory = "#{pathname.dirname}/html"
+    erb = ERB.new file_system.load "#{html_directory}/#{$1}.erb"
     erb.result(caller_binding)
   end
 
@@ -100,7 +105,7 @@ class ChartBase
     issues_id = next_id
 
     issue_descriptions.sort! { |a, b| a[0].key_as_i <=> b[0].key_as_i }
-    erb = ERB.new file_system.load "#{@html_directory}/collapsible_issues_panel.erb"
+    erb = ERB.new file_system.load File.join(html_directory, 'collapsible_issues_panel.erb')
     erb.result(binding)
   end
 
@@ -125,6 +130,21 @@ class ChartBase
     result
   end
 
+  def working_days_annotation
+    holidays.each_with_index.collect do |range, index|
+      <<~TEXT
+        holiday#{index}: {
+          drawTime: 'beforeDraw',
+          type: 'box',
+          xMin: '#{range.begin}T00:00:00',
+          xMax: '#{range.end}T23:59:59',
+          backgroundColor: #{CssVariable.new('--non-working-days-color').to_json},
+          borderColor: #{CssVariable.new('--non-working-days-color').to_json}
+        },
+      TEXT
+    end.join
+  end
+
   # Return only the board columns for the current board.
   def current_board
     if @board_id.nil?
@@ -144,8 +164,7 @@ class ChartBase
   def completed_issues_in_range include_unstarted: false
     issues.select do |issue|
       cycletime = issue.board.cycletime
-      stopped_time = cycletime.stopped_time(issue)
-      started_time = cycletime.started_time(issue)
+      started_time, stopped_time = cycletime.started_stopped_times(issue)
 
       stopped_time &&
         date_range.include?(stopped_time.to_date) && # Remove outside range
@@ -162,40 +181,54 @@ class ChartBase
     end
   end
 
-  def header_text text = nil
-    @header_text = text if text
+  def header_text text = :none
+    @header_text = text unless text == :none
     @header_text
   end
 
-  def description_text text = nil
-    @description_text = text if text
+  def description_text text = :none
+    @description_text = text unless text == :none
     @description_text
   end
 
+  # Convert a number like 1234567 into the string "1,234,567"
   def format_integer number
     number.to_s.reverse.scan(/.{1,3}/).join(',').reverse
   end
 
-  def format_status name_or_id, board:, is_category: false
-    begin
-      statuses = board.possible_statuses.expand_statuses([name_or_id])
-    rescue StatusNotFoundError => e
-      return "<span style='color: red'>#{name_or_id}</span>"
+  # object will be either a Status or a ChangeItem
+  # if it's a ChangeItem then use_old_status will specify whether we're using the new or old
+  # Either way, is_category will format the category rather than the status
+  def format_status object, board:, is_category: false, use_old_status: false
+    status = nil
+    error_message = nil
+
+    case object
+    when ChangeItem
+      id = use_old_status ? object.old_value_id : object.value_id
+      status = board.possible_statuses.find_by_id(id)
+      if status.nil?
+        error_message = use_old_status ? object.old_value : object.value
+      end
+    when Status
+      status = object
+    else
+      raise "Unexpected type: #{object.class}"
     end
 
-    status = statuses.first
+    return "<span style='color: red'>#{error_message}</span>" if error_message
+
     color = status_category_color status
 
     visibility = ''
     if is_category == false && board.visible_columns.none? { |column| column.status_ids.include? status.id }
       visibility = icon_span(
-      title: "Not visible: The status #{status.name.inspect} is not mapped to any column and will not be visible",
-      icon: ' 👀'
-    )
-
+        title: "Not visible: The status #{status.name.inspect} is not mapped to any column and will not be visible",
+        icon: ' 👀'
+      )
     end
-    text = is_category ? status.category_name : status.name
-    "<span title='Category: #{status.category_name}'>#{color_block color.name} #{text}</span>#{visibility}"
+    text = is_category ? status.category.name : status.name
+    "<span title='Category: #{status.category.name}'>#{color_block color.name} #{text}</span>#{visibility}"
   end
 
   def icon_span title:, icon:
@@ -203,11 +236,11 @@ class ChartBase
   end
 
   def status_category_color status
-    case status.category_name
-    when 'To Do' then CssVariable['--status-category-todo-color']
-    when 'In Progress' then CssVariable['--status-category-inprogress-color']
-    when 'Done' then CssVariable['--status-category-done-color']
-    else 'black' # Theoretically impossible but seen in prod.
+    case status.category.key
+    when 'new' then CssVariable['--status-category-todo-color']
+    when 'indeterminate' then CssVariable['--status-category-inprogress-color']
+    when 'done' then CssVariable['--status-category-done-color']
+    else CssVariable['--status-category-unknown-color'] # Theoretically impossible but seen in prod.
     end
   end
 
@@ -227,7 +260,10 @@ class ChartBase
 
   def color_block color, title: nil
     result = +''
-    result << "<div class='color_block' style='background: var(#{color});'"
+    result << "<div class='color_block' style='"
+    result << "background: #{CssVariable[color]};" if color
+    result << 'visibility: hidden;' unless color
+    result << "'"
     result << " title=#{title.inspect}" if title
     result << '></div>'
     result

data/lib/jirametrics/css_variable.rb

@@ -4,7 +4,7 @@ class CssVariable
   attr_reader :name
 
   def self.[](name)
-    if name.start_with? '--'
+    if name.is_a?(String) && name.start_with?('--')
       CssVariable.new name
     else
       name

data/lib/jirametrics/cycletime_config.rb

@@ -8,10 +8,14 @@ class CycleTimeConfig
 
   attr_reader :label, :parent_config
 
-  def initialize parent_config:, label:, block:, today: Date.today
+  def initialize parent_config:, label:, block:, file_system: nil, today: Date.today
     @parent_config = parent_config
     @label = label
     @today = today
+
+    # 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
 
@@ -26,31 +30,78 @@ class CycleTimeConfig
   end
 
   def in_progress? issue
-    started_time(issue) && stopped_time(issue).nil?
+    started_time, stopped_time = started_stopped_times(issue)
+    started_time && stopped_time.nil?
   end
 
   def done? issue
-    stopped_time(issue)
+    started_stopped_times(issue).last
   end
 
   def started_time issue
-    @start_at.call(issue)
+    @file_system.deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
+    started_stopped_times(issue).first
   end
 
   def stopped_time issue
-    @stop_at.call(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, author: 'unknown', artificial: true
+  end
+
+  def started_stopped_changes issue
+    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
+
+    [started, stopped]
+  end
+
+  def started_stopped_times issue
+    started, stopped = started_stopped_changes(issue)
+    [started&.time, stopped&.time]
+  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 = started_time(issue)
-    stop = stopped_time(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_time(issue)
+    start = started_stopped_times(issue).first
     stop = today || @today || Date.today
     return nil if start.nil? || stop.nil?
 

data/lib/jirametrics/cycletime_histogram.rb

@@ -5,10 +5,14 @@ require 'jirametrics/groupable_issue_chart'
 class CycletimeHistogram < ChartBase
   include GroupableIssueChart
   attr_accessor :possible_statuses
+  attr_reader :show_stats
 
   def initialize block
     super()
 
+    percentiles [50, 85, 98]
+    @show_stats = true
+
     header_text 'Cycletime Histogram'
     description_text <<-HTML
       <p>
@@ -26,21 +30,40 @@ class CycletimeHistogram < ChartBase
     end
   end
 
+  def percentiles percs = nil
+    @percentiles = percs unless percs.nil?
+    @percentiles
+  end
+
+  def disable_stats
+    @show_stats = false
+  end
+
   def run
     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) }
+    histogram_issues = stopped_issues.select { |issue| issue.board.cycletime.started_stopped_times(issue).first }
     rules_to_issues = group_issues histogram_issues
 
+    the_stats = {}
+
+    overall_stats = stats_for histogram_data: histogram_data_for(issues: histogram_issues), percentiles: @percentiles
+    the_stats[:all] = overall_stats
     data_sets = rules_to_issues.keys.collect do |rules|
+      the_issue_type = rules.label
+      the_histogram = histogram_data_for(issues: rules_to_issues[rules])
+      the_stats[the_issue_type] = stats_for histogram_data: the_histogram, percentiles: @percentiles if @show_stats
+
       data_set_for(
-        histogram_data: histogram_data_for(issues: rules_to_issues[rules]),
-        label: rules.label,
+        histogram_data: the_histogram,
+        label: the_issue_type,
         color: rules.color
       )
     end
 
+    return "<h1>#{@header_text}</h1>No data matched the selected criteria. Nothing to show." if data_sets.empty?
+
     wrap_and_render(binding, __FILE__)
   end
 
@@ -53,6 +76,48 @@ class CycletimeHistogram < ChartBase
     count_hash
   end
 
+  def stats_for histogram_data:, percentiles:
+    return {} if histogram_data.empty?
+
+    total_values = histogram_data.values.sum
+
+    # Calculate the average
+    weighted_sum = histogram_data.reduce(0) { |sum, (value, frequency)| sum + (value * frequency) }
+    average = total_values.zero? ? 0 : weighted_sum.to_f / total_values
+
+    # Find the mode (or modes!) and the spread of the distribution
+    sorted_histogram = histogram_data.sort_by { |_value, frequency| frequency }
+    max_freq = sorted_histogram[-1][1]
+    mode = sorted_histogram.select { |_v, f| f == max_freq }
+
+    minmax = histogram_data.keys.minmax
+
+    # Calculate percentiles
+    sorted_values = histogram_data.keys.sort
+    cumulative_counts = {}
+    cumulative_sum = 0
+
+    sorted_values.each do |value|
+      cumulative_sum += histogram_data[value]
+      cumulative_counts[value] = cumulative_sum
+    end
+
+    percentile_results = {}
+    percentiles.each do |percentile|
+      rank = (percentile / 100.0) * total_values
+      percentile_value = sorted_values.find { |value| cumulative_counts[value] >= rank }
+      percentile_results[percentile] = percentile_value
+    end
+
+    {
+      average: average,
+      mode: mode.collect(&:first).sort,
+      min: minmax[0],
+      max: minmax[1],
+      percentiles: percentile_results
+    }
+  end
+
   def data_set_for histogram_data:, label:, color:
     keys = histogram_data.keys.sort
     {

data/lib/jirametrics/cycletime_scatterplot.rb

@@ -24,7 +24,7 @@ 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
 
     init_configuration_block block do
@@ -53,10 +53,7 @@ class CycletimeScatterplot < ChartBase
   def create_datasets completed_issues
     data_sets = []
 
-    groups = group_issues completed_issues
-
-    groups.each_key do |rules|
-      completed_issues_by_type = groups[rules]
+    group_issues(completed_issues).each do |rules, completed_issues_by_type|
       label = rules.label
       color = rules.color
       percent_line = calculate_percent_line completed_issues_by_type
@@ -117,7 +114,7 @@ class CycletimeScatterplot < ChartBase
 
     {
       y: cycle_time,
-      x: chart_format(issue.board.cycletime.stopped_time(issue)),
+      x: chart_format(issue.board.cycletime.started_stopped_times(issue).last),
       title: ["#{issue.key} : #{issue.summary} (#{label_days(cycle_time)})"]
     }
   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,9 +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
+    started, stopped = issue.board.cycletime.started_stopped_dates(issue)
 
     rules.issue_hint = "(age: #{label_days (rules.current_date - started + 1).to_i})" if started
 

data/lib/jirametrics/daily_wip_by_blocked_stalled_chart.rb

@@ -39,8 +39,8 @@ class DailyWipByBlockedStalledChart < DailyWipChart
   end
 
   def default_grouping_rules issue:, rules:
-    started = issue.board.cycletime.started_time(issue)
-    stopped_date = issue.board.cycletime.stopped_time(issue)&.to_date
+    started, stopped = issue.board.cycletime.started_stopped_times(issue)
+    stopped_date = stopped&.to_date
 
     date = rules.current_date
     change = issue.blocked_stalled_by_date(date_range: date..date, chart_end_time: time_range.end)[date]

data/lib/jirametrics/daily_wip_by_parent_chart.rb

@@ -3,10 +3,6 @@
 require 'jirametrics/daily_wip_chart'
 
 class DailyWipByParentChart < DailyWipChart
-  def initialize block
-    super(block)
-  end
-
   def default_header_text
     'Daily WIP, grouped by the parent ticket (Epic, Feature, etc)'
   end