jirametrics 2.0 → 2.12.1

data/lib/jirametrics/change_item.rb

@@ -1,51 +1,67 @@
 # 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, :time, :author_raw
+  attr_accessor :value, :old_value
 
-  def initialize raw:, time:, author:, artificial: false
-    # raw will only ever be nil in a test and in that case field and value should be passed in
+  def initialize raw:, author_raw:, time:, artificial: false
     @raw = raw
+    @author_raw = author_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
     @artificial = artificial
-    @author = author
   end
 
-  def status? = (field == 'status')
+  def author
+    @author_raw&.[]('displayName') || @author_raw&.[]('name') || 'Unknown author'
+  end
 
-  def flagged? = (field == 'Flagged')
+  def author_icon_url
+    @author_raw&.[]('avatarUrls')&.[]('16x16')
+  end
 
+  def artificial? = @artificial
+  def assignee? = (field == 'assignee')
+  def comment? = (field == 'comment')
+  def due_date? = (field == 'duedate')
+  def flagged? = (field == 'Flagged')
+  def issue_type? = field == 'issuetype'
+  def labels? = (field == 'labels')
+  def link? = (field == 'Link')
   def priority? = (field == 'priority')
-
   def resolution? = (field == 'resolution')
-
-  def artificial? = @artificial
-
   def sprint? = (field == 'Sprint')
+  def status? = (field == 'status')
 
-  def story_points? = (field == 'Story Points')
-
-  def link? = (field == 'Link')
+  # 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 = "ChangeItem(field: #{field.inspect}, value: #{value.inspect}, time: \"#{@time}\""
-    message += ', artificial' if artificial?
-    message += ')'
+    message = +''
+    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
   end
 
   def inspect = to_s
 
   def == other
-    field.eql?(other.field) && value.eql?(other.value) && time.to_s.eql?(other.time.to_s)
+    field.eql?(other.field) && value.eql?(other.value) && time_to_s(time).eql?(time_to_s(other.time))
   end
 
   def current_status_matches *status_names_or_ids
@@ -77,4 +93,23 @@ class ChangeItem
       end
     end
   end
+
+  def field_as_human_readable
+    case @field
+    when 'duedate' then 'Due date'
+    when 'timeestimate' then 'Time estimate'
+    when 'timeoriginalestimate' then 'Time original estimate'
+    when 'issuetype' then 'Issue type'
+    when 'IssueParentAssociation' then 'Issue parent association'
+    else @field.capitalize
+    end
+  end
+
+  private
+
+  def time_to_s time
+    # MRI and JRuby return different strings for to_s() so we have to explicitly provide a full
+    # format so that tests work under both environments.
+    time.strftime '%Y-%m-%d %H:%M:%S %z'
+  end
 end

data/lib/jirametrics/chart_base.rb

@@ -2,25 +2,19 @@
 
 class ChartBase
   attr_accessor :timezone_offset, :board_id, :all_boards, :date_range,
-    :time_range, :data_quality, :holiday_dates, :settings
+    :time_range, :data_quality, :holiday_dates, :settings, :issues, :file_system, :users
   attr_writer :aggregated_project
-  attr_reader :issues, :canvas_width, :canvas_height
+  attr_reader :canvas_width, :canvas_height
 
   @@chart_counter = 0
 
   def initialize
     @chart_colors = {
-      'dark:Story' => 'green',
-      'dark:Task' => 'blue',
-      'dark:Bug' => 'orange',
-      'dark:Defect' => 'orange',
-      'dark:Spike' => '#9400D3', # dark purple
-      'light:Story' => '#90EE90',
-      'light:Task' => '#87CEFA',
-      'light:Bug' => '#ffdab9',
-      'light:Defect' => 'orange',
-      'light:Epic' => '#fafad2',
-      'light:Spike' => '#DDA0DD' # light purple
+      'Story'  => CssVariable['--type-story-color'],
+      'Task'   => CssVariable['--type-task-color'],
+      'Bug'    => CssVariable['--type-bug-color'],
+      'Defect' => CssVariable['--type-bug-color'],
+      'Spike'  => CssVariable['--type-spike-color']
     }
     @canvas_width = 800
     @canvas_height = 200
@@ -31,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
@@ -39,16 +38,21 @@ 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.read "#{@html_directory}/#{$1}.erb"
+    erb = ERB.new file_system.load "#{html_directory}/#{$1}.erb"
     erb.result(caller_binding)
   end
 
-  # Render the file and then wrap it with standard headers and quality checks.
-  def wrap_and_render caller_binding, file
+  def render_top_text caller_binding
     result = +''
     result << "<h1>#{@header_text}</h1>" if @header_text
     result << ERB.new(@description_text).result(caller_binding) if @description_text
+    result
+  end
+
+  # Render the file and then wrap it with standard headers and quality checks.
+  def wrap_and_render caller_binding, file
+    result = +''
+    result << render_top_text(caller_binding)
     result << render(caller_binding, file)
     result
   end
@@ -57,8 +61,8 @@ class ChartBase
     @@chart_counter += 1
   end
 
-  def color_for type:, shade: :dark
-    @chart_colors["#{shade}:#{type}"] ||= random_color
+  def color_for type:
+    @chart_colors[type] ||= random_color
   end
 
   def label_days days
@@ -100,7 +104,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.read "#{@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 +129,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 +163,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
@@ -153,17 +171,6 @@ class ChartBase
     end
   end
 
-  def sprints_in_time_range board
-    board.sprints.select do |sprint|
-      sprint_end_time = sprint.completed_time || sprint.end_time
-      sprint_start_time = sprint.start_time
-      next false if sprint_start_time.nil?
-
-      time_range.include?(sprint_start_time) || time_range.include?(sprint_end_time) ||
-        (sprint_start_time < time_range.begin && sprint_end_time > time_range.end)
-    end || []
-  end
-
   def chart_format object
     if object.is_a? Time
       # "2022-04-09T11:38:30-07:00"
@@ -173,41 +180,66 @@ class ChartBase
     end
   end
 
-  def header_text text
-    @header_text = text
+  def header_text text = :none
+    @header_text = text unless text == :none
+    @header_text
   end
 
-  def description_text text
-    @description_text = 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 RuntimeError => e
-      return "<span style='color: red'>#{name_or_id}</span>" if e.message.match?(/^Status not found:/)
-
-      throw e
+  # 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
-    raise "Expected exactly one match and got #{statuses.inspect} for #{name_or_id.inspect}" if statuses.size > 1
 
-    status = statuses.first
+    return "<span style='color: red'>#{error_message}</span>" if error_message
+
     color = status_category_color status
 
-    text = is_category ? status.category_name : status.name
-    "<span style='color: #{color}'>#{text}</span>"
+    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: ' 👀'
+      )
+    end
+    text = is_category ? status.category : status
+    "<span title='Category: #{status.category}'>#{color_block color.name} #{text}</span>#{visibility}"
+  end
+
+  def icon_span title:, icon:
+    "<span title='#{title}' style='font-size: 0.8em;'>#{icon}</span>"
   end
 
   def status_category_color status
-    case status.category_name
-    when nil then 'black'
-    when 'To Do' then 'gray'
-    when 'In Progress' then 'blue'
-    when 'Done' then 'green'
+    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
 
@@ -225,15 +257,23 @@ class ChartBase
     @canvas_responsive
   end
 
-  def filter_issues &block
-    @filter_issues_block = block
+  def color_block color, title: nil
+    result = +''
+    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
   end
 
-  def issues= issues
-    @issues = issues
-    return unless @filter_issues_block
-
-    @issues = issues.filter_map { |i| @filter_issues_block.call(i) }.uniq
-    puts @issues.collect(&:key).join(', ')
+  def describe_non_working_days
+    <<-TEXT
+      <div class='p'>
+        The #{color_block '--non-working-days-color'} vertical bars indicate non-working days; weekends
+        and any other holidays mentioned in the configuration.
+      </div>
+    TEXT
   end
 end

data/lib/jirametrics/columns_config.rb

@@ -34,6 +34,10 @@ class ColumnsConfig
     @columns << [:string, label, proc]
   end
 
+  def integer label, proc
+    @columns << [:integer, label, proc]
+  end
+
   def column_entry_times board_id: nil
     @file_config.project_config.find_board_by_id(board_id).visible_columns.each do |column|
       date column.name, first_time_in_status(*column.status_ids)

data/lib/jirametrics/css_variable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class CssVariable
+  attr_reader :name
+
+  def self.[](name)
+    if name.is_a?(String) && name.start_with?('--')
+      CssVariable.new name
+    else
+      name
+    end
+  end
+
+  def initialize name
+    @name = name
+  end
+
+  def to_json(*_args)
+    "getComputedStyle(document.body).getPropertyValue('#{@name}')"
+  end
+
+  def to_s
+    "var(#{@name})"
+  end
+
+  def inspect
+    "CssVariable['#{@name}']"
+  end
+
+  def == other
+    self.class == other.class && @name == other.name
+  end
+end

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, artificial: true, author_raw: nil
+  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 = nil
+  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
     {