jirametrics 1.0.0 → 2.11

data/lib/jirametrics/aging_work_table.rb

@@ -3,39 +3,62 @@
 require 'jirametrics/chart_base'
 
 class AgingWorkTable < ChartBase
-  attr_accessor :today, :board_id
+  attr_accessor :today
+  attr_reader :any_scrum_boards
 
   def initialize block
     super()
-    @blocked_icon = '🛑'
-    @expedited_icon = '🔥'
-    @stalled_icon = '🟧'
     @stalled_threshold = 5
-    @dead_icon = '⬛'
     @dead_threshold = 45
     @age_cutoff = 0
 
-    instance_eval(&block) if block
+    header_text 'Aging Work Table'
+    description_text <<-TEXT
+      <p>
+        This chart shows all active (started but not completed) work, ordered from oldest at the top to
+        newest at the bottom.
+      </p>
+      <p>
+        If there are expedited items that haven't yet started then they're at the bottom of the table.
+        By the very definition of expedited, if we haven't started them already, we'd better get on that.
+      </p>
+      <p>
+        Legend:
+        <ul>
+        <li><b>E:</b> Whether this item is <b>E</b>xpedited.</li>
+        <li><b>B/S:</b> Whether this item is either <b>B</b>locked or <b>S</b>talled.</li>
+        <li><b>Forecast:</b> A forecast of how long it is likely to take to finish this work item.</li>
+        </ul>
+      </p>
+    TEXT
+
+    instance_eval(&block)
   end
 
   def run
-    @today = date_range.end
-    aging_issues = select_aging_issues
+    initialize_calculator
+    aging_issues = select_aging_issues + expedited_but_not_started
 
-    expedited_but_not_started = @issues.select do |issue|
-      cycletime = issue.board.cycletime
-      cycletime.started_time(issue).nil? && cycletime.stopped_time(issue).nil? && issue.expedited?
-    end
-    aging_issues += expedited_but_not_started.sort_by(&:created)
+    wrap_and_render(binding, __FILE__)
+  end
+
+  # This is its own method simply so the tests can initialize the calculator without doing a full run.
+  def initialize_calculator
+    @today = date_range.end
+    @calculator = BoardMovementCalculator.new board: current_board, issues: issues, today: @today
+  end
 
-    render(binding, __FILE__)
+  def expedited_but_not_started
+    @issues.select do |issue|
+      started_time, stopped_time = issue.board.cycletime.started_stopped_times(issue)
+      started_time.nil? && stopped_time.nil? && issue.expedited?
+    end.sort_by(&:created)
   end
 
   def select_aging_issues
     aging_issues = @issues.select do |issue|
       cycletime = issue.board.cycletime
-      started = cycletime.started_time(issue)
-      stopped = cycletime.stopped_time(issue)
+      started, stopped = cycletime.started_stopped_times(issue)
       next false if started.nil? || stopped
       next true if issue.blocked_on_date?(@today, end_time: time_range.end) || issue.expedited?
 
@@ -46,47 +69,33 @@ class AgingWorkTable < ChartBase
     aging_issues.sort { |a, b| b.board.cycletime.age(b, today: @today) <=> a.board.cycletime.age(a, today: @today) }
   end
 
-  def icon_span title:, icon:
-    "<span title='#{title}' style='font-size: 0.8em;'>#{icon}</span>"
-  end
-
   def expedited_text issue
     return unless issue.expedited?
 
     name = issue.raw['fields']['priority']['name']
-    icon_span(title: "Expedited: Has a priority of &quot;#{name}&quot;", icon: @expedited_icon)
+    color_block '--expedited-color', title: "Expedited: Has a priority of &quot;#{name}&quot;"
   end
 
   def blocked_text issue
-    started_time = issue.board.cycletime.started_time(issue)
+    started_time, _stopped_time = issue.board.cycletime.started_stopped_times(issue)
     return nil if started_time.nil?
 
     current = issue.blocked_stalled_changes(end_time: time_range.end)[-1]
     if current.blocked?
-      icon_span title: current.reasons, icon: @blocked_icon
+      color_block '--blocked-color', title: current.reasons
     elsif current.stalled?
       if current.stalled_days && current.stalled_days > @dead_threshold
-        icon_span(
+        color_block(
+          '--dead-color',
           title: "Dead? Hasn&apos;t had any activity in #{label_days current.stalled_days}. " \
-            'Does anyone still care about this?',
-          icon: @dead_icon
+            'Does anyone still care about this?'
         )
       else
-        icon_span(
-          title: current.reasons,
-          icon: @stalled_icon
-        )
+        color_block '--stalled-color', title: current.reasons
       end
     end
   end
 
-  def unmapped_status_text issue
-    icon_span(
-      title: "The status #{issue.status.name.inspect} is not mapped to any column and will not be visible",
-      icon: ' ⁉️'
-    )
-  end
-
   def fix_versions_text issue
     issue.fix_versions.collect do |fix|
       if fix.released?
@@ -119,8 +128,38 @@ class AgingWorkTable < ChartBase
     end.join('<br />')
   end
 
-  def current_status_visible? issue
-    issue.board.visible_columns.any? { |column| column.status_ids.include? issue.status.id }
+  def dates_text issue
+    date = date_range.end
+    due = issue.due_date
+    message = nil
+
+    days_remaining, error = @calculator.forecasted_days_remaining_and_message issue: issue, today: @today
+
+    unless error
+      if due
+        if due < date
+          message = "Due: <b>#{due}</b> (#{label_days (@today - due).to_i} ago)"
+          error = 'Overdue'
+        elsif due == date
+          message = 'Due: <b>today</b>'
+        else
+          error = 'Due date at risk' if date_range.end + days_remaining > due
+          message = "Due: <b>#{due}</b> (#{label_days (due - @today).to_i})"
+        end
+      else
+        "#{label_days days_remaining} left."
+      end
+    end
+
+    text = +''
+    text << "<span title='#{error}' style='color: red'>ⓘ </span>" if error
+    if days_remaining
+      text << "#{label_days days_remaining} left"
+    else
+      text << 'Unable to forecast'
+    end
+    text << ' | ' << message if message
+    text
   end
 
   def age_cutoff age = nil
@@ -128,10 +167,6 @@ class AgingWorkTable < ChartBase
     @age_cutoff
   end
 
-  def any_scrum_boards?
-    @any_scrum_boards
-  end
-
   def parent_hierarchy issue
     result = []
 

data/lib/jirametrics/anonymizer.rb

@@ -12,6 +12,7 @@ class Anonymizer
     @all_boards = @project_config.all_boards
     @possible_statuses = @project_config.possible_statuses
     @date_adjustment = date_adjustment
+    @file_system = project_config.exporter.file_system
   end
 
   def run
@@ -20,7 +21,7 @@ class Anonymizer
     # anonymize_issue_statuses
     anonymize_board_names
     shift_all_dates unless @date_adjustment.zero?
-    puts 'Anonymize done'
+    @file_system.log 'Anonymize done'
   end
 
   def random_phrase
@@ -28,9 +29,9 @@ class Anonymizer
     # just try again. In every case we've seen, it's worked on the second attempt, but we'll be
     # cautious and try five times.
     5.times do |i|
-      return RandomWord.phrases.next.gsub(/_/, ' ')
+      return RandomWord.phrases.next.tr('_', ' ')
     rescue # rubocop:disable Style/RescueStandardError We don't care what exception was thrown.
-      puts "Random word blew up on attempt #{i + 1}"
+      @file_system.log "Random word blew up on attempt #{i + 1}"
     end
   end
 
@@ -45,7 +46,7 @@ class Anonymizer
 
       issue.issue_links.each do |link|
         other_issue = link.other_issue
-        next if other_issue.key =~ /^ANON-\d+$/ # Already anonymized?
+        next if other_issue.key.match?(/^ANON-\d+$/) # Already anonymized?
 
         other_issue.raw['key'] = "ANON-#{counter += 1}"
         other_issue.raw['fields']['summary'] = random_phrase
@@ -55,7 +56,7 @@ class Anonymizer
 
   def anonymize_column_names
     @all_boards.each_key do |board_id|
-      puts "Anonymizing column names for board #{board_id}"
+      @file_system.log "Anonymizing column names for board #{board_id}"
 
       column_name = 'Column-A'
       @all_boards[board_id].visible_columns.each do |column|
@@ -93,7 +94,7 @@ class Anonymizer
   end
 
   def anonymize_issue_statuses
-    puts 'Anonymizing issue statuses and status categories'
+    @file_system.log 'Anonymizing issue statuses and status categories'
     status_name_hash = build_status_name_hash
 
     @issues.each do |issue|
@@ -130,7 +131,7 @@ class Anonymizer
   end
 
   def shift_all_dates
-    puts "Shifting all dates by #{@date_adjustment} days"
+    @file_system.log "Shifting all dates by #{@date_adjustment} days"
     @issues.each do |issue|
       issue.changes.each do |change|
         change.time = change.time + @date_adjustment
@@ -179,7 +180,7 @@ class Anonymizer
   end
 
   def anonymize_board_names
-    @all_boards.values.each do |board|
+    @all_boards.each_value do |board|
       board.raw['name'] = "#{random_phrase} board"
     end
   end

data/lib/jirametrics/blocked_stalled_change.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require 'jirametrics/value_equality'
+
 class BlockedStalledChange
+  include ValueEquality
   attr_reader :time, :blocking_issue_keys, :flag, :status, :stalled_days, :status_is_blocking
 
   def initialize time:, flagged: nil, status: nil, status_is_blocking: true, blocking_issue_keys: nil, stalled_days: nil
@@ -12,20 +15,12 @@ class BlockedStalledChange
     @time = time
   end
 
-  def blocked? = @flag || blocked_by_status? || @blocking_issue_keys
-  def stalled? = @stalled_days || stalled_by_status?
+  def blocked? = !!(@flag || blocked_by_status? || @blocking_issue_keys)
+  def stalled? = !!(@stalled_days || stalled_by_status?)
   def active? = !blocked? && !stalled?
 
-  def blocked_by_status? = (@status && @status_is_blocking)
-  def stalled_by_status? = (@status && !@status_is_blocking)
-
-  def ==(other)
-    (other.class == self.class) && (other.state == state)
-  end
-
-  def state
-    instance_variables.map { |variable| instance_variable_get variable }
-  end
+  def blocked_by_status? = !!(@status && @status_is_blocking)
+  def stalled_by_status? = !!(@status && !@status_is_blocking)
 
   def reasons
     result = []
@@ -40,4 +35,24 @@ class BlockedStalledChange
     end
     result.join(', ')
   end
+
+  def as_symbol
+    if blocked?
+      :blocked
+    elsif stalled?
+      :stalled
+    else
+      :active
+    end
+  end
+
+  def inspect
+    text = "BlockedStalledChange(time: '#{@time}', "
+    if active?
+      text << 'Active'
+    else
+      text << reasons
+    end
+    text << ')'
+  end
 end

data/lib/jirametrics/board.rb

@@ -1,53 +1,53 @@
 # frozen_string_literal: true
 
 class Board
-  attr_reader :visible_columns, :raw, :possible_statuses, :sprints, :backlog_statuses
-  attr_accessor :cycletime, :project_config, :expedited_priority_names
+  attr_reader :visible_columns, :raw, :possible_statuses, :sprints, :board_type
+  attr_accessor :cycletime, :project_config
 
-  def initialize raw:, possible_statuses: StatusCollection.new
+  def initialize raw:, possible_statuses:
     @raw = raw
     @board_type = raw['type']
     @possible_statuses = possible_statuses
     @sprints = []
-    @expedited_priority_names = []
 
     columns = raw['columnConfig']['columns']
+    ensure_uniqueness_of_column_names! columns
 
     # For a Kanban board, the first column here will always be called 'Backlog' and will NOT be
     # visible on the board. If the board is configured to have a kanban backlog then it will have
     # statuses matched to it and otherwise, there will be no statuses.
-    if kanban?
-      assert_jira_behaviour_true(columns[0]['name'] == 'Backlog') do
-        "Expected first column to be called Backlog: #{raw}"
-      end
+    columns = columns.drop(1) if kanban?
+
+    @backlog_statuses = []
+    @visible_columns = columns.filter_map do |column|
+      # It's possible for a column to be defined without any statuses and in this case, it won't be visible.
+      BoardColumn.new column unless status_ids_from_column(column).empty?
+    end
+  end
 
-      @backlog_statuses = @possible_statuses.expand_statuses(status_ids_from_column columns[0]) do |unknown_status|
-        # Yet another "theoretically impossible and yet we've seen it in production" moment
-        puts "Status #{unknown_status.inspect} is defined as being in the backlog for board #{name.inspect}:#{id} " \
-          'and yet it\'s not defined in the list of possible statuses available to the project. Check your Jira ' \
-          'configuration'
+  def backlog_statuses
+    if @backlog_statuses.empty? && kanban?
+      status_ids = status_ids_from_column raw['columnConfig']['columns'].first
+      @backlog_statuses = status_ids.filter_map do |id|
+        @possible_statuses.find_by_id id
       end
-      columns = columns[1..]
-    else
-      # We currently don't know how to get the backlog status for a Scrum board
-      @backlog_statuses = []
     end
+    @backlog_statuses
+  end
 
-    @visible_columns = columns.collect do |column|
-      # It's possible for a column to be defined without any statuses and in this case, it won't be visible.
-      BoardColumn.new column unless status_ids_from_column(column).empty?
-    end.compact
+  def server_url_prefix
+    raise "Cannot parse self: #{@raw['self'].inspect}" unless @raw['self'] =~ /^(https?:\/\/.+)\/rest\//
+
+    $1
   end
 
   def url
     # Strangely, the URL isn't anywhere in the returned data so we have to fabricate it.
-    raise "Cannot parse self: #{@raw['self']}" unless @raw['self'] =~ /^(https?:\/\/[^\/]+)\//
-
-    "#{$1}/secure/RapidBoard.jspa?rapidView=#{id}"
+    "#{server_url_prefix}/secure/RapidBoard.jspa?rapidView=#{id}"
   end
 
   def status_ids_from_column column
-    column['statuses'].collect { |status| status['id'].to_i }
+    column['statuses']&.collect { |status| status['id'].to_i } || []
   end
 
   def status_ids_in_or_right_of_column column_name
@@ -61,7 +61,7 @@ class Board
     end
 
     unless found_it
-      column_names = @visible_columns.collect(&:name).collect(&:inspect).join(', ')
+      column_names = @visible_columns.collect { |c| c.name.inspect }.join(', ')
       raise "No visible column with name: #{column_name.inspect} Possible options are: #{column_names}"
     end
     status_ids
@@ -79,7 +79,42 @@ class Board
     @raw['id'].to_i
   end
 
+  def project_id
+    location = @raw['location']
+    return nil unless location
+
+    location['id'] if location['type'] == 'project'
+  end
+
   def name
     @raw['name']
   end
+
+  def accumulated_status_ids_per_column
+    accumulated_status_ids = []
+    visible_columns.reverse.filter_map do |column|
+      next if column == @fake_column
+
+      accumulated_status_ids += column.status_ids
+      [column.name, accumulated_status_ids.dup]
+    end.reverse
+  end
+
+  def ensure_uniqueness_of_column_names! json
+    all_names = []
+    json.each do |column_json|
+      name = column_json['name']
+      if all_names.include? name
+        (2..).each do |i|
+          new_name = "#{name}-#{i}"
+          next if all_names.include?(new_name)
+
+          name = new_name
+          column_json['name'] = new_name
+          break
+        end
+      end
+      all_names << name
+    end
+  end
 end

data/lib/jirametrics/board_config.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class BoardConfig
-  attr_reader :id, :project_config
+  attr_reader :id, :project_config, :board
 
   def initialize id:, block:, project_config:
     @id = id
@@ -11,7 +11,6 @@ class BoardConfig
 
   def run
     @board = @project_config.all_boards[id]
-    @board.expedited_priority_names = []
 
     instance_eval(&@block)
   end
@@ -22,10 +21,15 @@ class BoardConfig
         'If so, remove it from there.'
     end
 
-    @board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
+    @board.cycletime = CycleTimeConfig.new(
+      parent_config: self, label: label, block: block, file_system: project_config.file_system
+    )
   end
 
   def expedited_priority_names *priority_names
-    @board.expedited_priority_names = priority_names unless priority_names.empty?
+    project_config.exporter.file_system.deprecated(
+      date: '2024-09-15', message: 'Expedited priority names are now specified in settings'
+    )
+    @project_config.settings['expedited_priority_names'] = priority_names
   end
 end

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