jirametrics 2.20.1 → 2.25

data/lib/jirametrics/atlassian_document_format.rb

@@ -23,105 +23,95 @@ class AtlassianDocumentFormat
     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
-    closing_tag = nil
-    node_attrs = node['attrs']
-
-    result = +''
-    case node['type']
-    when 'blockquote'
-      result << '<blockquote>'
-      closing_tag = '</blockquote>'
-    when 'bulletList'
-      result << '<ul>'
-      closing_tag = '</ul>'
-    when 'codeBlock'
-      result << '<code>'
-      closing_tag = '</code>'
-    when 'date'
-      result << Time.at(node_attrs['timestamp'].to_i / 1000, in: @timezone_offset).to_date.to_s
-    when 'decisionItem'
-      result << '<li>'
-      closing_tag = '</li>'
-    when 'decisionList'
-      result << '<div>Decisions<ul>'
-      closing_tag = '</ul></div>'
-    when 'emoji'
-      result << node_attrs['text']
-    when 'expand'
-      # TODO: Maybe, someday, make this actually expandable. For now it's always open
-      result << "<div>#{node_attrs['title']}</div>"
-    when 'hardBreak'
-      result << '<br />'
-    when 'heading'
-      level = node_attrs['level']
-      result << "<h#{level}>"
-      closing_tag = "</h#{level}>"
-    when 'inlineCard'
-      url = node_attrs['url']
-      result << "[Inline card]: <a href='#{url}'>#{url}</a>"
-    when 'listItem'
-      result << '<li>'
-      closing_tag = '</li>'
-    when 'media'
-      text = node_attrs['alt'] || node_attrs['id']
-      result << "Media: #{text}"
-    when 'mediaSingle', 'mediaGroup'
-      result << '<div>'
-      closing_tag = '</div>'
-    when 'mention'
-      user = node_attrs['text']
-      result << "<b>#{user}</b>"
-    when 'orderedList'
-      result << '<ol>'
-      closing_tag = '</ol>'
-    when 'panel'
-      type = node_attrs['panelType']
-      result << "<div>#{type.upcase}</div>"
-    when 'paragraph'
-      result << '<p>'
-      closing_tag = '</p>'
-    when 'rule'
-      result << '<hr />'
-    when 'status'
-      text = node_attrs['text']
-      result << text
-    when 'table'
-      result << '<table>'
-      closing_tag = '</table>'
-    when 'tableCell'
-      result << '<td>'
-      closing_tag = '</td>'
-    when 'tableHeader'
-      result << '<th>'
-      closing_tag = '</th>'
-    when 'tableRow'
-      result << '<tr>'
-      closing_tag = '</tr>'
-    when 'text'
-      marks = adf_marks_to_html node['marks']
-      result << marks.collect(&:first).join
-      result << node['text']
-      result << marks.collect(&:last).join
-    when 'taskItem'
-      state = node_attrs['state'] == 'TODO' ? '☐' : '☑'
-      result << "<li>#{state} "
-      closing_tag = '</li>'
-    when 'taskList'
-      result << "<ul class='taskList'>"
-      closing_tag = '</ul>'
-    else
-      result << "<p>Unparseable section: #{node['type']}</p>"
+    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
 
-    node['content']&.each do |child|
-      result << adf_node_to_html(child)
+  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
-
-    result << closing_tag if closing_tag
-    result
   end
 
   def adf_marks_to_html list
@@ -157,4 +147,14 @@ class AtlassianDocumentFormat
     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?

data/lib/jirametrics/board.rb

@@ -4,18 +4,18 @@ class Board
   attr_reader :visible_columns, :raw, :possible_statuses, :sprints
   attr_accessor :cycletime, :project_config
 
-  def initialize raw:, possible_statuses:
+  def initialize raw:, possible_statuses:, features: []
     @raw = raw
     @possible_statuses = possible_statuses
     @sprints = []
+    @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.
-    columns = columns.drop(1) if kanban?
+    # 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|
@@ -25,7 +25,7 @@ class Board
   end
 
   def backlog_statuses
-    if @backlog_statuses.empty? && kanban?
+    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
@@ -67,8 +67,20 @@ class Board
   end
 
   def board_type = raw['type']
-  def kanban? = (board_type == 'kanban')
-  def scrum? = (board_type == 'scrum')
+
+  def scrum?
+    return true if board_type == 'scrum'
+    return false unless board_type == 'simple'
+
+    @features.any? { |f| f.name == 'jsw.agility.sprints' && f.enabled? }
+  end
+
+  def kanban?
+    return true if board_type == 'kanban'
+    return false unless board_type == 'simple'
+
+    !scrum?
+  end
 
   def id
     @raw['id'].to_i
@@ -116,4 +128,8 @@ class Board
   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

@@ -24,7 +24,8 @@ class BoardConfig
     end
 
     @board.cycletime = CycleTimeConfig.new(
-      parent_config: self, label: label, block: block, file_system: project_config.file_system,
+      possible_statuses: project_config.possible_statuses,
+      label: label, block: block, file_system: project_config.file_system,
       settings: project_config.settings
     )
   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

@@ -10,7 +10,7 @@ class BoardMovementCalculator
   end
 
   def moves_backwards? issue
-    started, stopped = issue.board.cycletime.started_stopped_times(issue)
+    started, stopped = issue.started_stopped_times
     return false unless started
 
     previous_column = nil
@@ -70,7 +70,7 @@ class BoardMovementCalculator
     @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)
+      issue_start, issue_done = issue.started_stopped_times
 
       # Skip if we can't tell when it started.
       next if issue_start.nil?

data/lib/jirametrics/cfd_data_builder.rb

@@ -0,0 +1,103 @@
+# 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
+    high_water_mark = nil
+    correction_open_since = nil
+    correction_windows = []
+    hwm_timeline = [] # sorted chronologically by date
+
+    issue.status_changes.each do |change|
+      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

data/lib/jirametrics/change_item.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class ChangeItem
-  attr_reader :field, :value_id, :old_value_id, :raw, :author_raw
+  attr_reader :field, :value_id, :old_value_id, :raw, :author_raw, :field_id
   attr_accessor :value, :old_value, :time
 
   def initialize raw:, author_raw:, time:, artificial: false
@@ -13,9 +13,15 @@ class ChangeItem
 
     @field = @raw['field']
     @value = @raw['toString']
-    @value_id = @raw['to'].to_i
     @old_value = @raw['fromString']
-    @old_value_id = @raw['from']&.to_i
+    if sprint?
+      @value_id = @raw['to'].split(', ').collect(&:to_i)
+      @old_value_id = (@raw['from'] || '').split(', ').collect(&:to_i)
+    else
+      @value_id = @raw['to']&.to_i
+      @old_value_id = @raw['from']&.to_i
+    end
+    @field_id = @raw['fieldId']
     @artificial = artificial
   end
 
@@ -40,6 +46,7 @@ class ChangeItem
   def resolution? = (field == 'resolution')
   def sprint? = (field == 'Sprint')
   def status? = (field == 'status')
+  def fix_version? = (field == 'Fix Version')
 
   # An alias for time so that logic accepting a Time, Date, or ChangeItem can all respond to :to_time
   def to_time = @time
@@ -48,12 +55,13 @@ class ChangeItem
     message = +''
     message << "ChangeItem(field: #{field.inspect}"
     message << ", value: #{value.inspect}"
-    message << ':' << value_id.inspect if status?
+    message << ':' << value_id.inspect if value_id
     if old_value
       message << ", old_value: #{old_value.inspect}"
-      message << ':' << old_value_id.inspect if status?
+      message << ':' << old_value_id.inspect if old_value_id
     end
     message << ", time: #{time_to_s(@time).inspect}"
+    message << ", field_id: #{@field_id.inspect}" if @field_id
     message << ', artificial' if artificial?
     message << ')'
     message

data/lib/jirametrics/chart_base.rb

@@ -3,7 +3,7 @@
 class ChartBase
   attr_accessor :timezone_offset, :board_id, :all_boards, :date_range,
     :time_range, :data_quality, :holiday_dates, :settings, :issues, :file_system,
-    :atlassian_document_format
+    :atlassian_document_format, :x_axis_title, :y_axis_title, :fix_versions
   attr_writer :aggregated_project
   attr_reader :canvas_width, :canvas_height
 
@@ -22,6 +22,14 @@ class ChartBase
     @canvas_responsive = true
   end
 
+  def call_before_run &proc
+    (@call_before_run_procs ||= []) << proc
+  end
+
+  def before_run
+    @call_before_run_procs&.each { |proc| proc.call }
+  end
+
   def aggregated_project?
     @aggregated_project
   end
@@ -72,10 +80,26 @@ class ChartBase
     "#{days} day#{'s' unless days == 1}"
   end
 
+  def label_hours hours
+    return 'unknown' if hours.nil?
+
+    "#{hours} hour#{'s' unless hours == 1}"
+  end
+
+  def label_minutes minutes
+    return 'unknown' if minutes.nil?
+
+    "#{minutes} minute#{'s' unless minutes == 1}"
+  end
+
   def label_issues count
     "#{count} issue#{'s' unless count == 1}"
   end
 
+  def to_human_readable number
+    number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+  end
+
   def daily_chart_dataset date_issues_list:, color:, label:, positive: true
     {
       type: 'bar',
@@ -147,6 +171,56 @@ class ChartBase
     end.join
   end
 
+  LABEL_POSITIONS = %w[5% 25% 45% 65%].freeze
+
+  def date_annotation
+    annotations = settings['date_annotations'] || []
+    in_range = annotations
+      .map { |a| [a, normalize_annotation_datetime(a['date'])] }
+      .select { |(_, dt)| date_range.cover?(Date.parse(dt)) }
+      .sort_by { |(_, dt)| dt }
+
+    positions = stagger_label_positions(in_range.map { |(_, dt)| dt })
+
+    in_range.each_with_index.collect do |(a, normalized), index|
+      <<~TEXT
+        dateAnnotation#{index}: {
+          type: 'line',
+          xMin: #{normalized.to_json},
+          xMax: #{normalized.to_json},
+          borderColor: 'rgba(0,0,0,0.7)',
+          borderWidth: 1,
+          label: {
+            display: true,
+            content: #{a['label'].to_json},
+            position: #{positions[index].to_json}
+          }
+        },
+      TEXT
+    end.join
+  end
+
+  def stagger_label_positions datetimes
+    return [] if datetimes.empty?
+
+    threshold_days = (date_range.end - date_range.begin).to_f / 5.0
+    slot = 0
+    [LABEL_POSITIONS[0]] + datetimes.each_cons(2).map do |a, b|
+      days_apart = (Date.parse(b) - Date.parse(a)).to_f.abs
+      slot = days_apart < threshold_days ? slot + 1 : 0
+      LABEL_POSITIONS[slot % LABEL_POSITIONS.size]
+    end
+  end
+
+  def normalize_annotation_datetime value
+    offset = timezone_offset || '+00:00'
+    if value.include?('T')
+      value.match?(/([+-]\d{2}:\d{2}|Z)$/) ? value : "#{value}#{offset}"
+    else
+      "#{value}T00:00:00#{offset}"
+    end
+  end
+
   # Return only the board columns for the current board.
   def current_board
     if @board_id.nil?
@@ -237,6 +311,13 @@ class ChartBase
     "<span title='#{title}' style='font-size: 0.8em;'>#{icon}</span>"
   end
 
+  def not_visible_text issue
+    reasons = issue.reasons_not_visible_on_board
+    return nil if reasons.empty?
+
+    "<span style='background: var(--warning-banner)'>Not visible on board: #{reasons.join(', ')}</span>"
+  end
+
   def status_category_color status
     case status.category.key
     when 'new' then CssVariable['--status-category-todo-color']
@@ -279,4 +360,46 @@ class ChartBase
       </div>
     TEXT
   end
+
+  # Set a cycletime for just this one chart, overriding the one for the report.
+  def cycletime &block
+    call_before_run do
+      @cycletime = CycleTimeConfig.new(
+        possible_statuses: possible_statuses, label: nil, block: block, file_system: file_system,
+        settings: settings
+      )
+    end
+  end
+
+  # Returns the cycletime in use right now, which may be specific to the chart or across the report.
+  def cycletime_for_issue issue
+    @cycletime || issue.board.cycletime
+  end
+
+  def seam_start type = 'chart'
+    "\n<!-- seam-start | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->"
+  end
+
+  def seam_end type = 'chart'
+    "\n<!-- seam-end | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->"
+  end
+
+  def render_axis_title axis_direction
+    text = case axis_direction
+    when :x
+      x_axis_title
+    when :y
+      y_axis_title
+    else
+      raise "Unexpected axis_direction: #{axis_direction}"
+    end
+    return '' unless text
+
+    <<~CONTENT
+      title: {
+          display: true,
+          text: "#{text}"
+        },
+    CONTENT
+  end
 end