jirametrics 1.0.0

data/lib/jirametrics/sprint_burndown.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+class SprintSummaryStats
+  attr_accessor :started, :added, :changed, :removed, :completed, :remaining, :points_values_changed
+
+  def initialize
+    @added = 0
+    @completed = 0
+    @removed = 0
+    @started = 0
+    @remaining = 0
+    @points_values_changed = false
+  end
+end
+
+class SprintBurndown < ChartBase
+  attr_reader :use_story_points, :use_story_counts
+  attr_accessor :board_id
+
+  def initialize
+    super()
+
+    @summary_stats = {}
+    header_text 'Sprint burndown'
+    description_text ''
+  end
+
+  def options= arg
+    case arg
+    when :points_only
+      @use_story_points = true
+      @use_story_counts = false
+    when :counts_only
+      @use_story_points = false
+      @use_story_counts = true
+    when :points_and_counts
+      @use_story_points = true
+      @use_story_counts = true
+    else
+      raise "Unexpected option: #{arg}"
+    end
+  end
+
+  def run
+    sprints = sprints_in_time_range all_boards[board_id]
+    return nil if sprints.empty?
+
+    change_data_by_sprint = {}
+    sprints.each do |sprint|
+      change_data = []
+      issues.each do |issue|
+        change_data += changes_for_one_issue(issue: issue, sprint: sprint)
+      end
+      change_data_by_sprint[sprint] = change_data.sort_by(&:time)
+    end
+
+    result = String.new
+    result << '<h1>Sprint Burndowns</h1>'
+
+    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
+    charts_to_generate.each do |data_method, y_axis_title|
+      @summary_stats.clear
+      data_sets = []
+      sprints.each_with_index do |sprint, index|
+        color = %w[blue orange green red brown][index % 5]
+        label = sprint.name
+        data = send(data_method, **{ sprint: sprint, change_data_for_sprint: change_data_by_sprint[sprint] })
+        data_sets << {
+          label: label,
+          data: data,
+          fill: false,
+          showLine: true,
+          borderColor: color,
+          backgroundColor: color,
+          stepped: true,
+          pointStyle: %w[rect circle] # First dot is visually different from the rest
+        }
+      end
+
+      legend = []
+      case data_method
+      when :data_set_by_story_counts
+        legend << '<b>Started</b>: Number of issues already in the sprint, when the sprint was started.'
+        legend << '<b>Completed</b>: Number of issues, completed during the sprint'
+        legend << '<b>Added</b>: Number of issues added in the middle of the sprint'
+        legend << '<b>Removed</b>: Number of issues removed while the sprint was in progress'
+      when :data_set_by_story_points
+        legend << '<b>Started</b>: Total count of story points when the sprint was started'
+        legend << '<b>Completed</b>: Count of story points completed during the sprint'
+        legend << '<b>Added</b>: Count of story points added in the middle of the sprint'
+        legend << '<b>Removed</b>: Count of story points removed while the sprint was in progress'
+      else
+        raise "Unexpected method #{data_method}"
+      end
+
+      result << render(binding, __FILE__)
+    end
+
+    result
+  end
+
+  # 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
+    ever_in_sprint = false
+    currently_in_sprint = false
+    change_data = []
+
+    issue_completed_time = issue.board.cycletime.stopped_time(issue)
+    completed_has_been_tracked = false
+
+    issue.changes.each do |change|
+      action = nil
+      value = nil
+
+      if change.sprint?
+        # We can get two sprint changes in a row that tell us the same thing so we have to verify
+        # that something actually changed.
+        in_change_item = sprint_in_change_item(sprint, change)
+        if currently_in_sprint == false && in_change_item
+          action = :enter_sprint
+          ever_in_sprint = true
+          value = story_points
+        elsif currently_in_sprint && in_change_item == false
+          action = :leave_sprint
+          value = -story_points
+        end
+        currently_in_sprint = in_change_item
+      elsif change.story_points? && (issue_completed_time.nil? || change.time < issue_completed_time)
+        action = :story_points
+        story_points = change.value&.to_f || 0.0
+        value = story_points - (change.old_value&.to_f || 0.0)
+      elsif completed_has_been_tracked == false && change.time == issue_completed_time
+        completed_has_been_tracked = true
+        action = :issue_stopped
+        value = -story_points
+      end
+
+      next unless action
+
+      change_data << SprintIssueChangeData.new(
+        time: change.time, issue: issue, action: action, value: value, story_points: story_points
+      )
+    end
+
+    return [] unless ever_in_sprint
+
+    change_data
+  end
+
+  def sprint_in_change_item sprint, change_item
+    change_item.raw['to'].split(/\s*,\s*/).any? { |id| id.to_i == sprint.id }
+  end
+
+  def data_set_by_story_points sprint:, change_data_for_sprint:
+    summary_stats = SprintSummaryStats.new
+    summary_stats.completed = 0.0
+
+    story_points = 0.0
+    start_data_written = false
+    data_set = []
+
+    issues_currently_in_sprint = []
+
+    change_data_for_sprint.each do |change_data|
+      if start_data_written == false && change_data.time >= sprint.start_time
+        data_set << {
+          y: story_points,
+          x: chart_format(sprint.start_time),
+          title: "Sprint started with #{story_points} points"
+        }
+        summary_stats.started = story_points
+        start_data_written = true
+      end
+
+      break if sprint.completed_time && change_data.time > sprint.completed_time
+
+      case change_data.action
+      when :enter_sprint
+        issues_currently_in_sprint << change_data.issue.key
+        story_points += change_data.story_points
+      when :leave_sprint
+        issues_currently_in_sprint.delete change_data.issue.key
+        story_points -= change_data.story_points
+      when :story_points
+        story_points += change_data.value if issues_currently_in_sprint.include? change_data.issue.key
+      end
+
+      next unless change_data.time >= sprint.start_time
+
+      message = nil
+      case change_data.action
+      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"
+        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
+      when :issue_stopped
+        story_points -= change_data.story_points
+        message = "Completed with #{change_data.story_points || 'no'} points"
+        issues_currently_in_sprint.delete change_data.issue.key
+        summary_stats.completed += change_data.story_points
+      when :leave_sprint
+        message = "Removed from sprint with #{change_data.story_points || 'no'} points"
+        summary_stats.removed += change_data.story_points
+      else
+        raise "Unexpected action: #{change_data.action}"
+      end
+
+      data_set << {
+        y: story_points,
+        x: chart_format(change_data.time),
+        title: "#{change_data.issue.key} #{message}"
+      }
+    end
+
+    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,
+        x: chart_format(sprint.start_time),
+        title: "Sprint started with #{story_points} points"
+      }
+      summary_stats.started = story_points
+    end
+
+    if sprint.completed_time
+      data_set << {
+        y: story_points,
+        x: chart_format(sprint.completed_time),
+        title: "Sprint ended with #{story_points} points unfinished"
+      }
+      summary_stats.remaining = story_points
+    end
+
+    unless sprint.completed_at?(time_range.end)
+      data_set << {
+        y: story_points,
+        x: chart_format(time_range.end),
+        title: "Sprint still active. #{story_points} points still in progress."
+      }
+    end
+
+    @summary_stats[sprint] = summary_stats
+    data_set
+  end
+
+  def data_set_by_story_counts sprint:, change_data_for_sprint:
+    summary_stats = SprintSummaryStats.new
+
+    data_set = []
+    issues_currently_in_sprint = []
+    start_data_written = false
+
+    change_data_for_sprint.each do |change_data|
+      if start_data_written == false && change_data.time >= sprint.start_time
+        data_set << {
+          y: issues_currently_in_sprint.size,
+          x: chart_format(sprint.start_time),
+          title: "Sprint started with #{issues_currently_in_sprint.size} stories"
+        }
+        summary_stats.started = issues_currently_in_sprint.size
+        start_data_written = true
+      end
+
+      break if sprint.completed_time && change_data.time > sprint.completed_time
+
+      case change_data.action
+      when :enter_sprint
+        issues_currently_in_sprint << change_data.issue.key
+      when :leave_sprint, :issue_stopped
+        issues_currently_in_sprint.delete change_data.issue.key
+      end
+
+      next unless change_data.time >= sprint.start_time
+
+      message = nil
+      case change_data.action
+      when :enter_sprint
+        message = 'Added to sprint'
+        summary_stats.added += 1
+      when :issue_stopped
+        message = 'Completed'
+        summary_stats.completed += 1
+      when :leave_sprint
+        message = 'Removed from sprint'
+        summary_stats.removed += 1
+      end
+
+      next unless message
+
+      data_set << {
+        y: issues_currently_in_sprint.size,
+        x: chart_format(change_data.time),
+        title: "#{change_data.issue.key} #{message}"
+      }
+    end
+
+    unless start_data_written
+      # There was nothing that triggered us to write the sprint started block so do it now.
+      data_set << {
+        y: issues_currently_in_sprint.size,
+        x: chart_format(sprint.start_time),
+        title: "Sprint started with #{issues_currently_in_sprint.size || 'no'} stories"
+      }
+    end
+
+    if sprint.completed_time
+      data_set << {
+        y: issues_currently_in_sprint.size,
+        x: chart_format(sprint.completed_time),
+        title: "Sprint ended with #{issues_currently_in_sprint.size} stories unfinished"
+      }
+      summary_stats.remaining = issues_currently_in_sprint.size
+    end
+
+    unless sprint.completed_at?(time_range.end)
+      # If the sprint is still active then we draw one final line to the end of the time range
+      data_set << {
+        y: issues_currently_in_sprint.size,
+        x: chart_format(time_range.end),
+        title: "Sprint still active. #{issues_currently_in_sprint.size} issues in progress."
+      }
+    end
+
+    @summary_stats[sprint] = summary_stats
+    data_set
+  end
+end

data/lib/jirametrics/sprint_issue_change_data.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class SprintIssueChangeData
+  attr_reader :time, :action, :value, :issue, :story_points
+
+  def initialize time:, action:, value:, issue:, story_points:
+    @time = time
+    @action = action
+    @value = value
+    @issue = issue
+    @story_points = story_points
+  end
+
+  def eql?(other)
+    (other.class == self.class) && (other.state == state)
+  end
+
+  def state
+    instance_variables.map { |variable| instance_variable_get variable }
+  end
+
+  def inspect
+    result = String.new
+    result << 'SprintIssueChangeData('
+    result << instance_variables.collect do |variable|
+      "#{variable}=#{instance_variable_get(variable).inspect}"
+    end.sort.join(', ')
+    result << ')'
+    result
+  end
+end

data/lib/jirametrics/status.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Status
+  attr_reader :id, :type, :category_name, :category_id
+  attr_accessor :name
+
+  def initialize name:, id:, category_name:, category_id:
+    @name = name
+    @id = id
+    @category_name = category_name
+    @category_id = category_id
+  end
+
+  def to_s
+    "Status(name=#{@name.inspect}, id=#{@id.inspect}," \
+      " category_name=#{@category_name.inspect}, category_id=#{@category_id.inspect})"
+  end
+
+  def eql?(other)
+    (other.class == self.class) && (other.state == state)
+  end
+
+  def state
+    instance_variables.map { |variable| instance_variable_get variable }
+  end
+end

data/lib/jirametrics/status_collection.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class StatusCollection
+  def initialize
+    @list = []
+  end
+
+  def filter_status_names category_name:, including: nil, excluding: nil
+    including = expand_statuses including
+    excluding = expand_statuses excluding
+
+    @list.collect do |status|
+      keep = status.category_name == category_name ||
+        including.any? { |s| s.name == status.name }
+      keep = false if excluding.any? { |s| s.name == status.name }
+
+      status.name if keep
+    end.compact
+  end
+
+  def expand_statuses names_or_ids
+    result = []
+    return result if names_or_ids.nil?
+
+    names_or_ids = [names_or_ids] unless names_or_ids.is_a? Array
+
+    names_or_ids.each do |name_or_id|
+      status = @list.find { |s| s.name == name_or_id || s.id == name_or_id }
+      if status.nil?
+        if block_given?
+          yield name_or_id
+          next
+        else
+          all_status_names = @list.collect { |s| "#{s.name.inspect}:#{s.id.inspect}" }.uniq.sort.join(', ')
+          raise "Status not found: #{name_or_id}. Possible statuses are: #{all_status_names}"
+        end
+      end
+
+      result << status
+    end
+    result
+  end
+
+  def todo including: nil, excluding: nil
+    filter_status_names category_name: 'To Do', including: including, excluding: excluding
+  end
+
+  def in_progress including: nil, excluding: nil
+    filter_status_names category_name: 'In Progress', including: including, excluding: excluding
+  end
+
+  def done including: nil, excluding: nil
+    filter_status_names category_name: 'Done', including: including, excluding: excluding
+  end
+
+  def find_by_name name
+    find { |status| status.name == name }
+  end
+
+  def find(&block)= @list.find(&block)
+  def collect(&block) = @list.collect(&block)
+  def each(&block) = @list.each(&block)
+  def select(&block) = @list.select(&block)
+  def <<(arg) = @list << arg
+  def empty? = @list.empty?
+  def clear = @list.clear
+end

data/lib/jirametrics/story_point_accuracy_chart.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+class StoryPointAccuracyChart < ChartBase
+  def initialize configuration_block = nil
+    super()
+
+    header_text 'Estimate Accuracy'
+    description_text <<-HTML
+      <p>
+        This chart graphs estimates against actual recorded cycle times. Since
+        estimates can change over time, we're graphing the estimate at the time that the story started.
+      </p>
+      <p>
+        The completed dots indicate cycletimes. The aging dots (if you turn them on) show the current
+        age of items, which will give you a hint as to where they might end up. If they're already
+        far to the right then you know you have a problem.
+      </p>
+    HTML
+
+    @y_axis_label = 'Story Point Estimates'
+    @y_axis_type = 'linear'
+    @y_axis_block = ->(issue, start_time) { story_points_at(issue: issue, start_time: start_time)&.to_f }
+    @y_axis_sort_order = nil
+
+    instance_eval(&configuration_block) if configuration_block
+  end
+
+  def run
+    data_sets = scan_issues
+
+    return '' if data_sets.empty?
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def scan_issues
+    aging_hash = {}
+    completed_hash = {}
+
+    issues.each do |issue|
+      cycletime = issue.board.cycletime
+      start_time = cycletime.started_time(issue)
+      stop_time = cycletime.stopped_time(issue)
+
+      next unless start_time
+
+      hash = stop_time ? completed_hash : aging_hash
+
+      estimate = @y_axis_block.call issue, start_time
+      cycle_time = ((stop_time&.to_date || date_range.end) - start_time.to_date).to_i + 1
+
+      next if estimate.nil?
+
+      key = [estimate, cycle_time]
+      (hash[key] ||= []) << issue
+    end
+
+    [
+      [completed_hash, 'Completed', '#66FF99', 'green', false],
+      [aging_hash, 'Still in progress', '#FFCCCB', 'red', true]
+    ].collect do |hash, label, fill_color, border_color, starts_hidden|
+      # We sort so that the smaller circles are in front of the bigger circles.
+      data = hash.sort(&hash_sorter).collect do |key, values|
+        estimate, cycle_time = *key
+        estimate_label = "#{estimate}#{'pts' if @y_axis_type == 'linear'}"
+        title = ["Estimate: #{estimate_label}, Cycletime: #{label_days(cycle_time)}, #{values.size} issues"] +
+          values.collect { |issue| "#{issue.key}: #{issue.summary}" }
+        {
+          'x' => cycle_time,
+          'y' => estimate,
+          'r' => values.size * 2,
+          'title' => title
+        }
+      end.compact
+      next if data.empty?
+
+      {
+        'label' => label,
+        'data' => data,
+        'fill' => false,
+        'showLine' => false,
+        'backgroundColor' => fill_color,
+        'borderColor' => border_color,
+        'hidden' => starts_hidden
+      }
+    end.compact
+  end
+
+  def hash_sorter
+    lambda do |arg1, arg2|
+      estimate1 = arg1[0][0]
+      estimate2 = arg2[0][0]
+      sample_count1 = arg1.size
+      sample_count2 = arg2.size
+
+      if @y_axis_sort_order
+        index1 = @y_axis_sort_order.index estimate1
+        index2 = @y_axis_sort_order.index estimate2
+
+        if index1.nil?
+          comparison = 1
+        elsif index2.nil?
+          comparison = -1
+        else
+          comparison = index1 <=> index2
+        end
+        return comparison unless comparison.zero?
+      end
+
+      sample_count2 <=> sample_count1
+    end
+  end
+
+  def story_points_at issue:, start_time:
+    story_points = nil
+    issue.changes.each do |change|
+      return story_points if change.time >= start_time
+
+      story_points = change.value if change.story_points?
+    end
+    story_points
+  end
+
+  def grouping range:, color: # rubocop:disable Lint/UnusedMethodArgument
+    deprecated message: 'The grouping declaration is no longer supported on the StoryPointEstimateChart ' \
+      'as we now use a bubble chart rather than colors'
+  end
+
+  def y_axis label:, sort_order: nil, &block
+    @y_axis_sort_order = sort_order
+    @y_axis_label = label
+    if sort_order
+      @y_axis_type = 'category'
+    else
+      @y_axis_type = 'linear'
+    end
+    @y_axis_block = block
+  end
+end

data/lib/jirametrics/throughput_chart.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class ThroughputChart < ChartBase
+  include GroupableIssueChart
+
+  attr_accessor :possible_statuses
+
+  def initialize block = nil
+    super()
+
+    header_text 'Throughput Chart'
+    description_text 'This chart shows how many items we completed per unit of time'
+
+    init_configuration_block(block) do
+      grouping_rules do |issue, rule|
+        rule.label = issue.type
+        rule.color = color_for type: issue.type
+      end
+    end
+  end
+
+  def run
+    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: 'gray', dashed: true
+      )
+    end
+
+    rules_to_issues.each_key do |rules|
+      data_sets << weekly_throughput_dataset(
+        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color
+      )
+    end
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def calculate_time_periods
+    first_day = @date_range.begin
+    first_day = case first_day.wday
+      when 0 then first_day + 1
+      when 1 then first_day
+      else first_day + (8 - first_day.wday)
+    end
+
+    periods = []
+
+    loop do
+      last_day = first_day + 6
+      return periods unless @date_range.include? last_day
+
+      periods << (first_day..last_day)
+      first_day = last_day + 1
+    end
+  end
+
+  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false
+    result = {
+      label: label,
+      data: throughput_dataset(periods: calculate_time_periods, completed_issues: completed_issues),
+      fill: false,
+      showLine: true,
+      borderColor: color,
+      lineTension: 0.4,
+      backgroundColor: color
+    }
+    result['borderDash'] = [10, 5] if dashed
+    result
+  end
+
+  def throughput_dataset periods:, completed_issues:
+    periods.collect do |period|
+      closed_issues = completed_issues.collect do |issue|
+        stop_date = issue.board.cycletime.stopped_time(issue)&.to_date
+        [stop_date, issue] if stop_date && period.include?(stop_date)
+      end.compact
+
+      date_label = "on #{period.end}"
+      date_label = "between #{period.begin} and #{period.end}" unless period.begin == period.end
+
+      { 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}" }
+      }
+    end
+  end
+end