jirametrics 2.10 → 2.30

data/lib/jirametrics/sprint_burndown.rb

@@ -29,6 +29,8 @@ class SprintBurndown < ChartBase
       </div>
       #{describe_non_working_days}
     TEXT
+    @x_axis_title = 'Date'
+    @y_axis_title = 'Items remaining'
   end
 
   def options= arg
@@ -48,8 +50,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|
@@ -63,7 +66,7 @@ class SprintBurndown < ChartBase
     result = +''
     result << render_top_text(binding)
 
-    possible_colours = (1..5).collect { |i| CssVariable["--sprint-burndown-sprint-color-#{i}"] }
+    possible_colours = (1..ChartBase::OKABE_ITO_PALETTE.size).collect { |i| CssVariable["--sprint-burndown-sprint-color-#{i}"] }
     charts_to_generate = []
     charts_to_generate << [:data_set_by_story_points, 'Story Points'] if @use_story_points
     charts_to_generate << [:data_set_by_story_counts, 'Story Count'] if @use_story_counts
@@ -110,6 +113,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?
@@ -121,12 +127,14 @@ class SprintBurndown < ChartBase
 
   # select all the changes that are relevant for the sprint. If this issue never appears in this sprint then return [].
   def changes_for_one_issue issue:, sprint:
-    story_points = 0.0
+    estimate = 0.0
     ever_in_sprint = false
     currently_in_sprint = false
     change_data = []
 
-    issue_completed_time = issue.board.cycletime.started_stopped_times(issue).last
+    estimate_display_name = current_board.estimation_configuration.display_name
+
+    issue_completed_time = issue.started_stopped_times.last
     completed_has_been_tracked = false
 
     issue.changes.each do |change|
@@ -140,26 +148,26 @@ class SprintBurndown < ChartBase
         if currently_in_sprint == false && in_change_item
           action = :enter_sprint
           ever_in_sprint = true
-          value = story_points
+          value = estimate
         elsif currently_in_sprint && in_change_item == false
           action = :leave_sprint
-          value = -story_points
+          value = -estimate
         end
         currently_in_sprint = in_change_item
-      elsif change.story_points? && (issue_completed_time.nil? || change.time < issue_completed_time)
+      elsif change.field == estimate_display_name && (issue_completed_time.nil? || change.time < issue_completed_time)
         action = :story_points
-        story_points = change.value.to_f
-        value = story_points - change.old_value.to_f
+        estimate = change.value.to_f
+        value = estimate - change.old_value.to_f
       elsif completed_has_been_tracked == false && change.time == issue_completed_time
         completed_has_been_tracked = true
         action = :issue_stopped
-        value = -story_points
+        value = -estimate
       end
 
       next unless action
 
       change_data << SprintIssueChangeData.new(
-        time: change.time, issue: issue, action: action, value: value, story_points: story_points
+        time: change.time, issue: issue, action: action, value: value, estimate: estimate
       )
     end
 
@@ -176,7 +184,7 @@ class SprintBurndown < ChartBase
     summary_stats = SprintSummaryStats.new
     summary_stats.completed = 0.0
 
-    story_points = 0.0
+    estimate = 0.0
     start_data_written = false
     data_set = []
 
@@ -185,11 +193,11 @@ class SprintBurndown < ChartBase
     change_data_for_sprint.each do |change_data|
       if start_data_written == false && change_data.time >= sprint.start_time
         data_set << {
-          y: story_points,
+          y: estimate,
           x: chart_format(sprint.start_time),
-          title: "Sprint started with #{story_points} points"
+          title: "Sprint started with #{estimate} points"
         }
-        summary_stats.started = story_points
+        summary_stats.started = estimate
         start_data_written = true
       end
 
@@ -198,12 +206,12 @@ class SprintBurndown < ChartBase
       case change_data.action
       when :enter_sprint
         issues_currently_in_sprint << change_data.issue.key
-        story_points += change_data.story_points
+        estimate += change_data.estimate
       when :leave_sprint
         issues_currently_in_sprint.delete change_data.issue.key
-        story_points -= change_data.story_points
+        estimate -= change_data.estimate
       when :story_points
-        story_points += change_data.value if issues_currently_in_sprint.include? change_data.issue.key
+        estimate += change_data.value if issues_currently_in_sprint.include? change_data.issue.key
       end
 
       next unless change_data.time >= sprint.start_time
@@ -213,26 +221,26 @@ class SprintBurndown < ChartBase
       when :story_points
         next unless issues_currently_in_sprint.include? change_data.issue.key
 
-        old_story_points = change_data.story_points - change_data.value
-        message = "Story points changed from #{old_story_points} points to #{change_data.story_points} points"
+        old_estimate = change_data.estimate - change_data.value
+        message = "Story points changed from #{old_estimate} points to #{change_data.estimate} points"
         summary_stats.points_values_changed = true
       when :enter_sprint
-        message = "Added to sprint with #{change_data.story_points || 'no'} points"
-        summary_stats.added += change_data.story_points
+        message = "Added to sprint with #{change_data.estimate || 'no'} points"
+        summary_stats.added += change_data.estimate
       when :issue_stopped
-        story_points -= change_data.story_points
-        message = "Completed with #{change_data.story_points || 'no'} points"
+        estimate -= change_data.estimate
+        message = "Completed with #{change_data.estimate || 'no'} points"
         issues_currently_in_sprint.delete change_data.issue.key
-        summary_stats.completed += change_data.story_points
+        summary_stats.completed += change_data.estimate
       when :leave_sprint
-        message = "Removed from sprint with #{change_data.story_points || 'no'} points"
-        summary_stats.removed += change_data.story_points
+        message = "Removed from sprint with #{change_data.estimate || 'no'} points"
+        summary_stats.removed += change_data.estimate
       else
         raise "Unexpected action: #{change_data.action}"
       end
 
       data_set << {
-        y: story_points,
+        y: estimate,
         x: chart_format(change_data.time),
         title: "#{change_data.issue.key} #{message}"
       }
@@ -241,27 +249,27 @@ class SprintBurndown < ChartBase
     unless start_data_written
       # There was nothing that triggered us to write the sprint started block so do it now.
       data_set << {
-        y: story_points,
+        y: estimate,
         x: chart_format(sprint.start_time),
-        title: "Sprint started with #{story_points} points"
+        title: "Sprint started with #{estimate} points"
       }
-      summary_stats.started = story_points
+      summary_stats.started = estimate
     end
 
     if sprint.completed_time
       data_set << {
-        y: story_points,
+        y: estimate,
         x: chart_format(sprint.completed_time),
-        title: "Sprint ended with #{story_points} points unfinished"
+        title: "Sprint ended with #{estimate} points unfinished"
       }
-      summary_stats.remaining = story_points
+      summary_stats.remaining = estimate
     end
 
     unless sprint.completed_at?(time_range.end)
       data_set << {
-        y: story_points,
+        y: estimate,
         x: chart_format(time_range.end),
-        title: "Sprint still active. #{story_points} points still in progress."
+        title: "Sprint still active. #{estimate} points still in progress."
       }
     end
 

data/lib/jirametrics/sprint_issue_change_data.rb

@@ -4,14 +4,14 @@ require 'jirametrics/value_equality'
 
 class SprintIssueChangeData
   include ValueEquality
-  attr_reader :time, :action, :value, :issue, :story_points
+  attr_reader :time, :action, :value, :issue, :estimate
 
-  def initialize time:, action:, value:, issue:, story_points:
+  def initialize time:, action:, value:, issue:, estimate:
     @time = time
     @action = action
     @value = value
     @issue = issue
-    @story_points = story_points
+    @estimate = estimate
   end
 
   def inspect

data/lib/jirametrics/status.rb

@@ -36,7 +36,10 @@ class Status
   end
 
   def self.from_raw raw
+    raise 'raw cannot be nil' if raw.nil?
+
     category_config = raw['statusCategory']
+    raise "statusCategory can't be nil in #{category_config.inspect}" if category_config.nil?
 
     Status.new(
       name: raw['name'],

data/lib/jirametrics/status_collection.rb

@@ -16,6 +16,13 @@ class StatusCollection
     @list.find { |status| status.id == id }
   end
 
+  def find_by_id! id
+    status = @list.find { |status| status.id == id }
+    raise "Can't find any status for id #{id} in #{self}" unless status
+
+    status
+  end
+
   def find_all_by_name identifier
     name, id = parse_name_id identifier
 

data/lib/jirametrics/stitcher.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class Stitcher < HtmlGenerator
+  class StitchContent
+    include ValueEquality
+
+    attr_reader :file, :title, :content, :type
+
+    def initialize file:, title:, type:, content:
+      @file = file
+      @title = title
+      @content = content
+      @type = type
+    end
+  end
+
+  attr_reader :loaded_files, :all_stitches
+
+  def initialize file_system:
+    super()
+    self.file_system = file_system
+    @all_stitches = []
+    @loaded_files = []
+  end
+
+  def run stitch_file:
+    output_filename = make_output_filename stitch_file
+    file_system.log "Creating file #{output_filename.inspect}", also_write_to_stderr: true
+    erb = ERB.new file_system.load(stitch_file)
+    @sections = [[erb.result(binding), :body]]
+    create_html output_filename: output_filename, settings: {}
+  end
+
+  def make_output_filename input_filename
+    if /^(.+)\.erb$/ =~ input_filename
+      "#{$1}.html"
+    else
+      "#{input_filename}.html"
+    end
+  end
+
+  def grab_by_title title, from_file:, type: 'chart'
+    parse_file from_file
+    stitch_content = @all_stitches.find { |s| s.file == from_file && s.title == title && s.type == type }
+    return stitch_content.content if stitch_content
+
+    file_system.error "Unable to find content in file #{from_file.inspect} matching title: #{title.inspect}"
+    ''
+  end
+
+  def parse_file filename
+    return false if @loaded_files.include? filename
+
+    # To match: <!-- seam-start | chart78 | GithubPrScatterplot | PR Scatterplot | chart -->
+    regex = /^<!-- seam-(?<seam>start|end) \| (?<id>[^|]+) \| (?<clazz>[^|]+) \| (?<title>[^|]+) \| (?<type>[^|]+) -->$/
+    content = nil
+    file_system.load(filename).lines do |line|
+      matches = line.match(regex)
+      if matches
+        if matches[:seam] == 'start'
+          content = +''
+        else
+          if content.nil? || content.strip.empty?
+            file_system.warning "Seam found with no content in #{filename.inspect}: " \
+              "id=#{matches[:id].strip.inspect}, class=#{matches[:clazz].strip.inspect}, " \
+              "title=#{matches[:title].strip.inspect}"
+          end
+          @all_stitches << Stitcher::StitchContent.new(
+            file: filename, title: matches[:title], type: matches[:type], content: content
+          )
+          content = nil
+        end
+      elsif content
+        content << line
+      end
+    end
+
+    @loaded_files << filename
+    true
+  end
+end

data/lib/jirametrics/throughput_by_completed_resolution_chart.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'jirametrics/throughput_chart'
+
+class ThroughputByCompletedResolutionChart < ThroughputChart
+  def initialize block
+    super
+    header_text 'Throughput, grouped by completion status and resolution'
+    description_text nil
+  end
+
+  def default_grouping_rules issue, rules
+    status, resolution = issue.status_resolution_at_done
+    if resolution
+      rules.label = "#{status.name}:#{resolution}"
+      rules.label_hint = "Status: #{status.name.inspect}:#{status.id}, resolution: #{resolution.inspect}"
+    else
+      rules.label = status.name
+      rules.label_hint = "Status: #{status.name.inspect}:#{status.id}"
+    end
+  end
+end

data/lib/jirametrics/throughput_chart.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cgi'
+
 class ThroughputChart < ChartBase
   include GroupableIssueChart
 
@@ -10,42 +12,54 @@ class ThroughputChart < ChartBase
 
     header_text 'Throughput Chart'
     description_text <<-TEXT
-      <div class="p">
-        This chart shows how many items we completed per week
+      <div>Throughput data is very useful for#{' '}
+        <a href="https://blog.mikebowler.ca/2024/06/02/probabilistic-forecasting/">probabilistic forecasting</a>,
+        to determine when we'll be done. Try it now with the
+        <a href="<%= throughput_forecaster_url %>" target="_blank" rel="noopener noreferrer">
+        Focused Objective throughput forecaster,</a> to see how long it would take to complete all of the
+        <%= @not_started_count %> items you currently have in your backlog.
       </div>
       #{describe_non_working_days}
     TEXT
+    @x_axis_title = nil
+    @y_axis_title = 'Count of items'
 
     init_configuration_block(block) do
-      grouping_rules do |issue, rule|
-        rule.label = issue.type
-        rule.color = color_for type: issue.type
-      end
+      grouping_rules { |issue, rule| default_grouping_rules(issue, rule) }
     end
   end
 
   def run
+    # This is saved as an instance variable so that it's accessible later when rendering the description text
+    @not_started_count = issues.count { |issue| issue.started_stopped_times.first.nil? }
+
     completed_issues = completed_issues_in_range include_unstarted: true
     rules_to_issues = group_issues completed_issues
     data_sets = []
-    if rules_to_issues.size > 1
-      data_sets << weekly_throughput_dataset(
-        completed_issues: completed_issues,
-        label: 'Totals',
-        color: CssVariable['--throughput_chart_total_line_color'],
-        dashed: true
-      )
-    end
+    total_data_set = weekly_throughput_dataset(
+      completed_issues: completed_issues,
+      label: 'Totals',
+      color: CssVariable['--throughput_chart_total_line_color'],
+      dashed: true
+    )
+    @throughput_samples = total_data_set[:data].collect { |d| d[:y] }
+    data_sets << total_data_set if rules_to_issues.size > 1
 
     rules_to_issues.each_key do |rules|
       data_sets << weekly_throughput_dataset(
-        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color
+        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color,
+        label_hint: rules.label_hint
       )
     end
 
     wrap_and_render(binding, __FILE__)
   end
 
+  def default_grouping_rules issue, rule
+    rule.label = issue.type
+    rule.color = color_for type: issue.type
+  end
+
   def calculate_time_periods
     first_day = @date_range.begin
     first_day = case first_day.wday
@@ -65,10 +79,22 @@ class ThroughputChart < ChartBase
     end
   end
 
-  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false
+  def calculate_custom_periods
+    last_days = @issue_periods.values.compact.uniq.sort
+    last_days.each_with_index.map do |last_day, i|
+      first_day = i.zero? ? @date_range.begin : last_days[i - 1] + 1
+      first_day..last_day
+    end
+  end
+
+  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false, label_hint: nil
+    periods = @issue_periods&.values&.any? ? calculate_custom_periods : calculate_time_periods
     result = {
       label: label,
-      data: throughput_dataset(periods: calculate_time_periods, completed_issues: completed_issues),
+      label_hint: label_hint,
+      data: throughput_dataset(
+        periods: periods, completed_issues: completed_issues, label_hint: label_hint
+      ),
       fill: false,
       showLine: true,
       borderColor: color,
@@ -79,20 +105,44 @@ class ThroughputChart < ChartBase
     result
   end
 
-  def throughput_dataset periods:, completed_issues:
+  def throughput_forecaster_url
+    params = {
+      throughputMode: 'data',
+      samplesText: @throughput_samples.join(','),
+      storyLow: @not_started_count,
+      storyHigh: @not_started_count
+    }
+
+    query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
+    "https://focusedobjective.com/throughput?#{query}"
+  end
+
+  def throughput_dataset periods:, completed_issues:, label_hint: nil
+    custom_mode = @issue_periods&.values&.any?
     periods.collect do |period|
       closed_issues = completed_issues.filter_map do |issue|
-        stop_date = issue.board.cycletime.started_stopped_dates(issue).last
-        [stop_date, issue] if stop_date && period.include?(stop_date)
+        stop_date = issue.started_stopped_dates.last
+        next unless stop_date
+
+        if custom_mode
+          [stop_date, issue] if @issue_periods[issue] == period.end
+        elsif period.include?(stop_date)
+          [stop_date, issue]
+        end
       end
 
       date_label = "on #{period.end}"
       date_label = "between #{period.begin} and #{period.end}" unless period.begin == period.end
 
-      { y: closed_issues.size,
+      with_label_hint = label_hint ? " with #{label_hint}" : ''
+      {
+        y: closed_issues.size,
         x: "#{period.end}T23:59:59",
-        title: ["#{closed_issues.size} items completed #{date_label}"] +
-          closed_issues.collect { |_stop_date, issue| "#{issue.key} : #{issue.summary}" }
+        title: ["#{closed_issues.size} items closed#{with_label_hint} #{date_label}"] +
+          closed_issues.collect do |_stop_date, issue|
+            hint = @issue_hints&.fetch(issue, nil)
+            "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
+          end
       }
     end
   end

data/lib/jirametrics/time_based_histogram.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class TimeBasedHistogram < ChartBase
+  include GroupableIssueChart
+
+  attr_reader :show_stats
+
+  def initialize
+    super
+
+    percentiles [50, 85, 98]
+    @show_stats = true
+  end
+
+  def percentiles percs = nil
+    @percentiles = percs unless percs.nil?
+    @percentiles
+  end
+
+  def disable_stats
+    @show_stats = false
+  end
+
+  def run
+    histogram_items = all_items
+    rules_to_items = group_issues histogram_items
+
+    the_stats = {}
+
+    overall_histogram = histogram_data_for(items: histogram_items).transform_values(&:size)
+    the_stats[:all] = stats_for histogram_data: overall_histogram, percentiles: @percentiles
+    data_sets = rules_to_items.keys.collect do |rules|
+      the_label = rules.label
+      the_histogram = histogram_data_for(items: rules_to_items[rules])
+      if @show_stats
+        the_stats[the_label] = stats_for(
+          histogram_data: the_histogram.transform_values(&:size), percentiles: @percentiles
+        )
+      end
+
+      data_set_for(
+        histogram_data: the_histogram,
+        label: the_label,
+        color: rules.color
+      )
+    end
+
+    if data_sets.empty?
+      return "<h1 class='foldable'>#{@header_text}</h1>" \
+             '<div>No data matched the selected criteria. Nothing to show.</div>'
+    end
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def histogram_data_for items:
+    items_hash = {}
+    items.each do |item|
+      days = value_for_item item
+      (items_hash[days] ||= []) << item if days.positive?
+    end
+    items_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 sort_items items
+    items
+  end
+
+  def label_for_item item, hint:
+    raise NotImplementedError, "#{self.class} must implement label_for_item"
+  end
+
+  def data_set_for histogram_data:, label:, color:
+    {
+      type: 'bar',
+      label: label,
+      data: histogram_data.keys.sort.filter_map do |days|
+        items = histogram_data[days]
+        next if items.empty?
+
+        {
+          x: days,
+          y: items.size,
+          title: [title_for_item(count: items.size, value: days)] +
+            sort_items(items).collect do |item|
+              hint = @issue_hints&.fetch(item, nil)
+              label_for_item(item, hint: hint)
+            end
+        }
+      end,
+      backgroundColor: color,
+      borderRadius: 0
+    }
+  end
+end