jirametrics 2.4 → 2.30

data/lib/jirametrics/atlassian_document_format.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+class AtlassianDocumentFormat
+  attr_reader :users
+
+  def initialize users:, timezone_offset:
+    @users = users
+    @timezone_offset = timezone_offset
+  end
+
+  def to_html input
+    if input.is_a? String
+      input
+        .gsub(/{color:(#\w{6})}([^{]+){color}/, '<span style="color: \1">\2</span>') # Colours
+        .gsub(/\[~accountid:([^\]]+)\]/) { expand_account_id $1 } # Tagged people
+        .gsub(/\[([^|]+)\|(https?[^\]]+)\]/, '<a href="\2">\1</a>') # URLs
+        .gsub("\n", '<br />')
+    elsif input&.[]('content')
+      input['content'].collect { |element| adf_node_to_html element }.join("\n")
+    else
+      # We have an actual ADF document with no content.
+      ''
+    end
+  end
+
+  def to_text input
+    if input.is_a? String
+      input
+    elsif input&.[]('content')
+      input['content'].collect { |element| adf_node_to_text element }.join
+    else
+      ''
+    end
+  end
+
+  # ADF is Atlassian Document Format
+  # https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
+  def adf_node_to_html node # rubocop:disable Metrics/CyclomaticComplexity
+    adf_node_render(node) do |n|
+      node_attrs = n['attrs']
+      case n['type']
+      when 'blockquote'                then ['<blockquote>', '</blockquote>']
+      when 'bulletList'                then ['<ul>', '</ul>']
+      when 'codeBlock'                 then ['<code>', '</code>']
+      when 'date'
+        [Time.at(node_attrs['timestamp'].to_i / 1000, in: @timezone_offset).to_date.to_s, nil]
+      when 'decisionItem', 'listItem'  then ['<li>', '</li>']
+      when 'decisionList'              then ['<div>Decisions<ul>', '</ul></div>']
+      when 'emoji', 'status'           then [node_attrs['text'], nil]
+      when 'expand'                    then ["<div>#{node_attrs['title']}</div>", nil]
+      when 'hardBreak'                 then ['<br />', nil]
+      when 'heading'
+        level = node_attrs['level']
+        ["<h#{level}>", "</h#{level}>"]
+      when 'inlineCard'
+        url = node_attrs['url']
+        ["[Inline card]: <a href='#{url}'>#{url}</a>", nil]
+      when 'media'
+        text = node_attrs['alt'] || node_attrs['id']
+        ["Media: #{text}", nil]
+      when 'mediaSingle', 'mediaGroup' then ['<div>', '</div>']
+      when 'mention'                   then ["<b>#{node_attrs['text']}</b>", nil]
+      when 'orderedList'               then ['<ol>', '</ol>']
+      when 'panel'                     then ["<div>#{node_attrs['panelType'].upcase}</div>", nil]
+      when 'paragraph'                 then ['<p>', '</p>']
+      when 'rule'                      then ['<hr />', nil]
+      when 'table'                     then ['<table>', '</table>']
+      when 'tableCell'                 then ['<td>', '</td>']
+      when 'tableHeader'               then ['<th>', '</th>']
+      when 'tableRow'                  then ['<tr>', '</tr>']
+      when 'text'
+        marks = adf_marks_to_html(n['marks'])
+        [marks.collect(&:first).join + n['text'], marks.collect(&:last).join]
+      when 'taskItem'
+        state = node_attrs['state'] == 'TODO' ? '☐' : '☑'
+        ["<li>#{state} ", '</li>']
+      when 'taskList'                  then ["<ul class='taskList'>", '</ul>']
+      else
+        ["<p>Unparseable section: #{n['type']}</p>", nil]
+      end
+    end
+  end
+
+  def adf_node_to_text node # rubocop:disable Metrics/CyclomaticComplexity
+    adf_node_render(node) do |n|
+      node_attrs = n['attrs']
+      case n['type']
+      when 'blockquote', 'bulletList', 'codeBlock',
+           'mediaSingle', 'mediaGroup',
+           'orderedList', 'table', 'taskList'  then ['', nil]
+      when 'date'
+        [Time.at(node_attrs['timestamp'].to_i / 1000, in: @timezone_offset).to_date.to_s, nil]
+      when 'decisionItem'              then ['- ', "\n"]
+      when 'decisionList'              then ["Decisions:\n", nil]
+      when 'emoji', 'mention', 'status' then [node_attrs['text'], nil]
+      when 'expand'                    then ["#{node_attrs['title']}\n", nil]
+      when 'hardBreak'                 then ["\n", nil]
+      when 'heading', 'paragraph', 'tableRow' then ['', "\n"]
+      when 'inlineCard'                then [node_attrs['url'], nil]
+      when 'listItem'                  then ['- ', nil]
+      when 'media'
+        text = node_attrs['alt'] || node_attrs['id']
+        ["Media: #{text}", nil]
+      when 'panel'                     then ["#{node_attrs['panelType'].upcase}\n", nil]
+      when 'rule'                      then ["---\n", nil]
+      when 'tableCell', 'tableHeader'  then ['', "\t"]
+      when 'text'                      then [n['text'], nil]
+      when 'taskItem'
+        state = node_attrs['state'] == 'TODO' ? '☐' : '☑'
+        ["#{state} ", "\n"]
+      else
+        ["[Unparseable: #{n['type']}]\n", nil]
+      end
+    end
+  end
+
+  def adf_marks_to_html list
+    return [] if list.nil?
+
+    mappings = [
+      ['strong', '<b>', '</b>'],
+      ['code', '<code>', '</code>'],
+      ['em', '<em>', '</em>'],
+      ['strike', '<s>', '</s>'],
+      ['underline', '<u>', '</u>']
+    ]
+
+    list.filter_map do |mark|
+      type = mark['type']
+      if type == 'textColor'
+        color = mark['attrs']['color']
+        ["<span style='color: #{color}'>", '</span>']
+      elsif type == 'link'
+        href = mark['attrs']['href']
+        title = mark['attrs']['title']
+        ["<a href='#{href}' title='#{title}'>", '</a>']
+      else
+        line = mappings.find { |key, _open, _close| key == type }
+        [line[1], line[2]] if line
+      end
+    end
+  end
+
+  def expand_account_id account_id
+    user = @users.find { |u| u.account_id == account_id }
+    text = account_id
+    text = "@#{user.display_name}" if user
+    "<span class='account_id'>#{text}</span>"
+  end
+
+  private
+
+  def adf_node_render node, &render_node
+    prefix, suffix = render_node.call(node)
+    result = +(prefix || '')
+    node['content']&.each { |child| result << adf_node_render(child, &render_node) }
+    result << suffix if suffix
+    result
+  end
+end

data/lib/jirametrics/bar_chart_range.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'jirametrics/value_equality'
+
+class BarChartRange
+  include ValueEquality
+
+  attr_accessor :start, :stop, :color, :title, :highlight
+
+  def initialize start:, stop:, color:, title:, highlight: false
+    @start = start
+    @stop = stop
+    @color = color
+    @title = title
+    @highlight = highlight
+  end
+end

data/lib/jirametrics/blocked_stalled_change.rb

@@ -4,10 +4,12 @@ require 'jirametrics/value_equality'
 
 class BlockedStalledChange
   include ValueEquality
-  attr_reader :time, :blocking_issue_keys, :flag, :status, :stalled_days, :status_is_blocking
+  attr_reader :time, :blocking_issue_keys, :flag, :flag_reason, :status, :stalled_days, :status_is_blocking
 
-  def initialize time:, flagged: nil, status: nil, status_is_blocking: true, blocking_issue_keys: nil, stalled_days: nil
+  def initialize time:, flagged: nil, flag_reason: nil, status: nil, status_is_blocking: true,
+    blocking_issue_keys: nil, stalled_days: nil
     @flag = flagged
+    @flag_reason = flag_reason
     @status = status
     @status_is_blocking = status_is_blocking
     @blocking_issue_keys = blocking_issue_keys
@@ -25,7 +27,7 @@ class BlockedStalledChange
   def reasons
     result = []
     if blocked?
-      result << 'Blocked by flag' if @flag
+      result << (@flag_reason ? "Blocked by flag: #{@flag_reason}" : 'Blocked by flag') if @flag
       result << "Blocked by status: #{@status}" if blocked_by_status?
       result << "Blocked by issues: #{@blocking_issue_keys.join(', ')}" if @blocking_issue_keys
     elsif stalled_by_status?
@@ -47,7 +49,7 @@ class BlockedStalledChange
   end
 
   def inspect
-    text = +"BlockedStalledChange(time: '#{@time}', "
+    text = "BlockedStalledChange(time: '#{@time}', "
     if active?
       text << 'Active'
     else

data/lib/jirametrics/board.rb

@@ -1,39 +1,39 @@
 # 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
+  attr_accessor :cycletime, :project_config
 
-  def initialize raw:, possible_statuses: StatusCollection.new
+  def initialize raw:, possible_statuses:, features: []
     @raw = raw
-    @board_type = raw['type']
     @possible_statuses = possible_statuses
     @sprints = []
-    @expedited_priority_names = []
+    @features = features
 
     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?
-      @backlog_statuses = @possible_statuses.expand_statuses(status_ids_from_column columns[0]) do |unknown_status|
-        # There is a status defined as being 'backlog' that is no longer being returned in statuses.
-        # We used to display a warning for this but honestly, there is nothing that anyone can do about it
-        # so now we just quietly ignore it.
-      end
-      columns = columns[1..]
-    else
-      # We currently don't know how to get the backlog status for a Scrum board
-      @backlog_statuses = []
-    end
+    # For a classic Kanban board (type 'kanban'), the first column will always be called 'Backlog'
+    # and will NOT be visible on the board. This does not apply to team-managed boards (type 'simple').
+    columns = columns.drop(1) if board_type == '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
 
+  def backlog_statuses
+    if @backlog_statuses.empty? && board_type == '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
+    end
+    @backlog_statuses
+  end
+
   def server_url_prefix
     raise "Cannot parse self: #{@raw['self'].inspect}" unless @raw['self'] =~ /^(https?:\/\/.+)\/rest\//
 
@@ -66,12 +66,28 @@ class Board
     status_ids
   end
 
+  def board_type = raw['type']
+
+  def scrum?
+    return true if board_type == 'scrum'
+    return false unless board_type == 'simple'
+
+    has_sprints_feature?
+  end
+
   def kanban?
-    @board_type == 'kanban'
+    return true if board_type == 'kanban'
+    return false unless board_type == 'simple'
+
+    !scrum?
   end
 
-  def scrum?
-    @board_type == 'scrum'
+  def team_managed_kanban?
+    board_type == 'simple' && !has_sprints_feature?
+  end
+
+  def has_sprints_feature?
+    @features.any? { |f| f.name == 'jsw.agility.sprints' && f.enabled? }
   end
 
   def id
@@ -88,4 +104,40 @@ class Board
   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
+
+  def estimation_configuration
+    EstimationConfiguration.new raw: raw['estimation']
+  end
+
+  def inspect
+    "Board(id: #{id}, name: #{name.inspect}, board_type: #{board_type.inspect})"
+  end
 end

data/lib/jirametrics/board_config.rb

@@ -11,9 +11,10 @@ class BoardConfig
 
   def run
     @board = @project_config.all_boards[id]
-    @board.expedited_priority_names = []
+    raise "Can't find board #{id.inspect} in #{@project_config.all_boards.keys.inspect}" unless @board
 
     instance_eval(&@block)
+    raise "Must specify a cycletime for board #{@id}" if @board.cycletime.nil?
   end
 
   def cycletime label = nil, &block
@@ -22,10 +23,17 @@ class BoardConfig
         'If so, remove it from there.'
     end
 
-    @board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
+    @board.cycletime = CycleTimeConfig.new(
+      possible_statuses: project_config.possible_statuses,
+      label: label, block: block, file_system: project_config.file_system,
+      settings: project_config.settings
+    )
   end
 
   def expedited_priority_names *priority_names
-    @board.expedited_priority_names = priority_names
+    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_feature.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class BoardFeature
+  def initialize raw:
+    @raw = raw
+  end
+
+  def name = @raw['feature']
+  def enabled? = (@raw['state'] == 'ENABLED')
+
+  def self.from_raw features_json
+    features_json['features']&.map { |f| new(raw: f) } || []
+  end
+end

data/lib/jirametrics/board_movement_calculator.rb

@@ -0,0 +1,155 @@
+# 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.started_stopped_times
+    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.started_stopped_times
+
+      # 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?
+
+    # This condition has been reported in production so we have a check for it. Having said that, we have no
+    # idea what conditions might make this possible and so there is no test for it.
+    if entry_time.nil?
+      message = "Unable to determine the time this issue entered column #{column_name.inspect} so no way to " \
+        'predict when it will be done'
+      return [nil, message]
+    end
+
+    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/cfd_data_builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class CfdDataBuilder
+  def initialize board:, issues:, date_range:, columns: nil
+    @board = board
+    @issues = issues
+    @date_range = date_range
+    @columns = columns || board.visible_columns
+  end
+
+  def run
+    column_map = build_column_map
+    issue_states = @issues.map { |issue| process_issue(issue, column_map) }
+
+    {
+      columns: @columns.map(&:name),
+      daily_counts: build_daily_counts(issue_states),
+      correction_windows: issue_states.flat_map { |s| s[:correction_windows] }
+    }
+  end
+
+  private
+
+  def build_column_map
+    map = {}
+    @columns.each_with_index do |column, index|
+      column.status_ids.each { |id| map[id] = index }
+    end
+    map
+  end
+
+  # Returns { hwm_timeline: [[date, hwm_value], ...], correction_windows: [...] }
+  def process_issue issue, column_map
+    start_time = issue.started_stopped_times.first
+    return { hwm_timeline: [], correction_windows: [] } if start_time.nil?
+
+    high_water_mark = nil
+    correction_open_since = nil
+    correction_windows = []
+    hwm_timeline = [] # sorted chronologically by date
+
+    issue.status_changes.each do |change|
+      next if change.time < start_time
+
+      col_index = column_map[change.value_id]
+      next if col_index.nil?
+
+      if high_water_mark.nil? || col_index > high_water_mark
+        # Forward movement: advance hwm, close any open correction window, record timeline entry
+        if correction_open_since
+          correction_windows << {
+            start_date: correction_open_since,
+            end_date: change.time.to_date,
+            column_index: high_water_mark
+          }
+          correction_open_since = nil
+        end
+        high_water_mark = col_index
+        hwm_timeline << [change.time.to_date, high_water_mark]
+      elsif col_index == high_water_mark && correction_open_since
+        # Same-column recovery: close the correction window without changing hwm or adding timeline entry
+        correction_windows << {
+          start_date: correction_open_since,
+          end_date: change.time.to_date,
+          column_index: high_water_mark
+        }
+        correction_open_since = nil
+      elsif col_index < high_water_mark
+        # Backwards movement: open correction window if not already open
+        correction_open_since ||= change.time.to_date
+      end
+    end
+
+    if correction_open_since
+      correction_windows << {
+        start_date: correction_open_since,
+        end_date: @date_range.end,
+        column_index: high_water_mark
+      }
+    end
+
+    { hwm_timeline: hwm_timeline, correction_windows: correction_windows }
+  end
+
+  def hwm_at hwm_timeline, date
+    result = nil
+    hwm_timeline.each do |timeline_date, hwm|
+      break if timeline_date > date
+
+      result = hwm
+    end
+    result
+  end
+
+  def build_daily_counts issue_states
+    column_count = @columns.size
+    @date_range.each_with_object({}) do |date, result|
+      counts = Array.new(column_count, 0)
+      issue_states.each do |state|
+        hwm = hwm_at(state[:hwm_timeline], date)
+        next if hwm.nil?
+
+        (0..hwm).each { |i| counts[i] += 1 }
+      end
+      result[date] = counts
+    end
+  end
+end