jirametrics 2.5 → 2.30

data/lib/jirametrics/change_item.rb

@@ -1,42 +1,67 @@
 # frozen_string_literal: true
 
 class ChangeItem
-  attr_reader :field, :value_id, :old_value_id, :raw, :author
+  attr_reader :field, :value_id, :old_value_id, :raw, :author_raw, :field_id
   attr_accessor :value, :old_value, :time
 
-  def initialize raw:, time:, author:, artificial: false
+  def initialize raw:, author_raw:, time:, artificial: false
     @raw = raw
+    @author_raw = author_raw
     @time = time
-    raise "Time must be an object of type Time in the correct timezone: #{@time}" if @time.is_a? String
+    raise 'ChangeItem.new() time cannot be nil' if time.nil?
+    raise "Time must be an object of type Time in the correct timezone: #{@time.inspect}" unless @time.is_a? Time
 
-    @field = field || @raw['field']
-    @value = value || @raw['toString']
-    @value_id = @raw['to'].to_i
+    @field = @raw['field']
+    @value = @raw['toString']
     @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
-    @author = author
   end
 
-  def status? = (field == 'status')
+  def author
+    @author_raw&.[]('displayName') || @author_raw&.[]('name') || 'Unknown author'
+  end
 
-  def flagged? = (field == 'Flagged')
+  def author_icon_url
+    @author_raw&.[]('avatarUrls')&.[]('16x16')
+  end
 
+  def artificial? = @artificial
+  def assignee? = (field == 'assignee')
+  def comment? = (field == 'comment')
+  def description? = (field == 'description')
+  def due_date? = (field == 'duedate')
+  def flagged? = (field == 'Flagged')
+  def issue_type? = field == 'issuetype'
+  def labels? = (field == 'labels')
+  def link? = (field == 'Link')
   def priority? = (field == 'priority')
-
   def resolution? = (field == 'resolution')
-
-  def artificial? = @artificial
-
   def sprint? = (field == 'Sprint')
+  def status? = (field == 'status')
+  def fix_version? = (field == 'Fix Version')
 
-  def story_points? = (field == 'Story Points')
-
-  def link? = (field == 'Link')
+  # An alias for time so that logic accepting a Time, Date, or ChangeItem can all respond to :to_time
+  def to_time = @time
 
   def to_s
     message = +''
-    message << "ChangeItem(field: #{field.inspect}, value: #{value.inspect}, time: #{time_to_s(@time).inspect}"
+    message << "ChangeItem(field: #{field.inspect}"
+    message << ", value: #{value.inspect}"
+    message << ':' << value_id.inspect if value_id
+    if old_value
+      message << ", old_value: #{old_value.inspect}"
+      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
@@ -78,6 +103,17 @@ class ChangeItem
     end
   end
 
+  def field_as_human_readable
+    case @field
+    when 'duedate' then 'Due date'
+    when 'timeestimate' then 'Time estimate'
+    when 'timeoriginalestimate' then 'Time original estimate'
+    when 'issuetype' then 'Issue type'
+    when 'IssueParentAssociation' then 'Issue parent association'
+    else @field.capitalize
+    end
+  end
+
   private
 
   def time_to_s time

data/lib/jirametrics/chart_base.rb

@@ -1,8 +1,20 @@
 # frozen_string_literal: true
 
 class ChartBase
+  # Okabe-Ito palette — perceptually distinct under the most common forms of colour blindness.
+  # Ordered from most- to least-commonly useful for chart series.
+  OKABE_ITO_PALETTE = %w[
+    #0072B2
+    #E69F00
+    #009E73
+    #56B4E9
+    #D55E00
+    #CC79A7
+    #F0E442
+  ].freeze
   attr_accessor :timezone_offset, :board_id, :all_boards, :date_range,
-    :time_range, :data_quality, :holiday_dates, :settings, :issues, :file_system
+    :time_range, :data_quality, :holiday_dates, :settings, :issues, :file_system,
+    :atlassian_document_format, :x_axis_title, :y_axis_title, :fix_versions
   attr_writer :aggregated_project
   attr_reader :canvas_width, :canvas_height
 
@@ -21,10 +33,23 @@ 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
 
+  def html_directory
+    pathname = Pathname.new(File.realpath(__FILE__))
+    "#{pathname.dirname}/html"
+  end
+
   def render caller_binding, file
     pathname = Pathname.new(File.realpath(file))
     basename = pathname.basename.to_s
@@ -33,14 +58,13 @@ class ChartBase
     # Insert a incrementing chart_id so that all the chart names on the page are unique
     caller_binding.eval "chart_id='chart#{next_id}'" # chart_id=chart3
 
-    @html_directory = "#{pathname.dirname}/html"
-    erb = ERB.new file_system.load "#{@html_directory}/#{$1}.erb"
+    erb = ERB.new file_system.load "#{html_directory}/#{$1}.erb"
     erb.result(caller_binding)
   end
 
   def render_top_text caller_binding
     result = +''
-    result << "<h1>#{@header_text}</h1>" if @header_text
+    result << "<h1 class='foldable'>#{@header_text}</h1>" if @header_text
     result << ERB.new(@description_text).result(caller_binding) if @description_text
     result
   end
@@ -62,13 +86,31 @@ class ChartBase
   end
 
   def label_days days
+    return 'unknown' if days.nil?
+
     "#{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',
@@ -100,7 +142,7 @@ class ChartBase
     issues_id = next_id
 
     issue_descriptions.sort! { |a, b| a[0].key_as_i <=> b[0].key_as_i }
-    erb = ERB.new file_system.load "#{@html_directory}/collapsible_issues_panel.erb"
+    erb = ERB.new file_system.load File.join(html_directory, 'collapsible_issues_panel.erb')
     erb.result(binding)
   end
 
@@ -125,6 +167,71 @@ class ChartBase
     result
   end
 
+  def working_days_annotation
+    holidays.each_with_index.collect do |range, index|
+      <<~TEXT
+        holiday#{index}: {
+          drawTime: 'beforeDraw',
+          type: 'box',
+          xMin: '#{range.begin}T00:00:00',
+          xMax: '#{range.end}T23:59:59',
+          backgroundColor: #{CssVariable.new('--non-working-days-color').to_json},
+          borderColor: #{CssVariable.new('--non-working-days-color').to_json}
+        },
+      TEXT
+    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?
@@ -144,8 +251,7 @@ class ChartBase
   def completed_issues_in_range include_unstarted: false
     issues.select do |issue|
       cycletime = issue.board.cycletime
-      stopped_time = cycletime.stopped_time(issue)
-      started_time = cycletime.started_time(issue)
+      started_time, stopped_time = cycletime.started_stopped_times(issue)
 
       stopped_time &&
         date_range.include?(stopped_time.to_date) && # Remove outside range
@@ -162,57 +268,79 @@ class ChartBase
     end
   end
 
-  def header_text text = nil
-    @header_text = text if text
+  def header_text text = :none
+    @header_text = text unless text == :none
     @header_text
   end
 
-  def description_text text = nil
-    @description_text = text if text
+  def description_text text = :none
+    @description_text = text unless text == :none
     @description_text
   end
 
+  # Convert a number like 1234567 into the string "1,234,567"
   def format_integer number
     number.to_s.reverse.scan(/.{1,3}/).join(',').reverse
   end
 
-  def format_status name_or_id, board:, is_category: false
-    begin
-      statuses = board.possible_statuses.expand_statuses([name_or_id])
-    rescue StatusNotFoundError => e
-      return "<span style='color: red'>#{name_or_id}</span>"
+  # object will be either a Status or a ChangeItem
+  # if it's a ChangeItem then use_old_status will specify whether we're using the new or old
+  # Either way, is_category will format the category rather than the status
+  def format_status object, board:, is_category: false, use_old_status: false
+    status = nil
+    error_message = nil
+
+    case object
+    when ChangeItem
+      id = use_old_status ? object.old_value_id : object.value_id
+      status = board.possible_statuses.find_by_id(id)
+      if status.nil?
+        error_message = use_old_status ? object.old_value : object.value
+      end
+    when Status
+      status = object
+    else
+      raise "Unexpected type: #{object.class}"
     end
 
-    status = statuses.first
+    return "<span style='color: red'>#{error_message}</span>" if error_message
+
     color = status_category_color status
 
     visibility = ''
     if is_category == false && board.visible_columns.none? { |column| column.status_ids.include? status.id }
       visibility = icon_span(
-      title: "Not visible: The status #{status.name.inspect} is not mapped to any column and will not be visible",
-      icon: ' 👀'
-    )
-
+        title: "Not visible: The status #{status.name.inspect} is not mapped to any column and will not be visible",
+        icon: ' 👀'
+      )
     end
-    text = is_category ? status.category_name : status.name
-    "<span title='Category: #{status.category_name}'>#{color_block color.name} #{text}</span>#{visibility}"
+    text = is_category ? status.category : status
+    "<span title='Category: #{status.category}'>#{color_block color.name} #{text}</span>#{visibility}"
   end
 
   def icon_span title:, icon:
     "<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_name
-    when 'To Do' then CssVariable['--status-category-todo-color']
-    when 'In Progress' then CssVariable['--status-category-inprogress-color']
-    when 'Done' then CssVariable['--status-category-done-color']
-    else 'black' # Theoretically impossible but seen in prod.
+    case status.category.key
+    when 'new' then CssVariable['--status-category-todo-color']
+    when 'indeterminate' then CssVariable['--status-category-inprogress-color']
+    when 'done' then CssVariable['--status-category-done-color']
+    else CssVariable['--status-category-unknown-color'] # Theoretically impossible but seen in prod.
     end
   end
 
   def random_color
-    "##{Random.bytes(3).unpack1('H*')}"
+    @palette_index = (@palette_index || -1) + 1
+    OKABE_ITO_PALETTE[@palette_index % OKABE_ITO_PALETTE.size]
   end
 
   def canvas width:, height:, responsive: true
@@ -227,7 +355,10 @@ class ChartBase
 
   def color_block color, title: nil
     result = +''
-    result << "<div class='color_block' style='background: var(#{color});'"
+    result << "<div class='color_block' style='"
+    result << "background: #{CssVariable[color]};" if color
+    result << 'visibility: hidden;' unless color
+    result << "'"
     result << " title=#{title.inspect}" if title
     result << '></div>'
     result
@@ -241,4 +372,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} -->\n"
+  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

data/lib/jirametrics/css_variable.rb

@@ -4,7 +4,7 @@ class CssVariable
   attr_reader :name
 
   def self.[](name)
-    if name.start_with? '--'
+    if name.is_a?(String) && name.start_with?('--')
       CssVariable.new name
     else
       name
@@ -16,7 +16,7 @@ class CssVariable
   end
 
   def to_json(*_args)
-    "getComputedStyle(document.body).getPropertyValue('#{@name}')"
+    "getComputedStyle(document.documentElement).getPropertyValue('#{@name}').trim()"
   end
 
   def to_s

data/lib/jirametrics/cumulative_flow_diagram.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'jirametrics/cfd_data_builder'
+
+class CumulativeFlowDiagram < ChartBase
+  # Used to embed a Chart.js segment callback (which contains JS functions) into
+  # a JSON-like dataset object. The custom to_json emits raw JS rather than a
+  # quoted string, following the same pattern as ExpeditedChart::EXPEDITED_SEGMENT.
+  class Segment
+    def initialize windows
+      # Build a JS array literal of [start_date, end_date] string pairs
+      @windows_js = windows
+        .map { |w| "[#{w[:start_date].to_json}, #{w[:end_date].to_json}]" }
+        .join(', ')
+    end
+
+    def to_json *_args
+      <<~JS
+        {
+          borderDash: function(ctx) {
+            const x = ctx.p1.parsed.x;
+            const windows = [#{@windows_js}];
+            return windows.some(function(w) {
+              return x >= new Date(w[0]).getTime() && x <= new Date(w[1]).getTime();
+            }) ? [6, 4] : undefined;
+          }
+        }
+      JS
+    end
+  end
+  private_constant :Segment
+
+  class CfdColumnRules < Rules
+    attr_accessor :color, :label, :label_hint
+  end
+  private_constant :CfdColumnRules
+
+  def initialize block
+    super()
+    header_text 'Cumulative Flow Diagram'
+    description_text <<~HTML
+      <div class="p">
+        A Cumulative Flow Diagram (CFD) shows how work accumulates across board columns over time.
+        Each coloured band represents a workflow stage. The top edge of the leftmost band shows
+        total work entered; the top edge of the rightmost band shows total work completed.
+      </div>
+      <div class="p">
+        A widening band means work is piling up in that stage — a bottleneck. Parallel top edges
+        (bands staying the same width) indicate smooth flow. Steep rises in the leftmost band
+        without corresponding rises on the right mean new work is arriving faster than it is
+        being finished.
+      </div>
+      <div class="p">
+        Dashed lines and hatched regions indicate periods where an item moved backwards through
+        the workflow (a correction). These highlight rework or process irregularities worth
+        investigating.
+      </div>
+      <div class="p">
+        The chart also overlays two trend lines and an interactive triangle. The <b>arrival rate</b>
+        trend line shows how fast work is entering the system; the <b>departure rate</b> trend line
+        shows how fast it is leaving. Move the mouse over the chart to see a Little's Law triangle
+        at that point in time, labelled with three derived metrics: <b>Work In Progress (WIP)</b> (items started
+        but not finished), <b>approximate average cycle time (CT)</b> (roughly how long an average item takes to complete), and
+        <b>average throughput (TP)</b> (items completed per day). Use the checkbox above the chart to toggle
+        between the triangle and the normal data tooltips.
+      </div>
+      <div class="p">
+        CT and TP require a future point C where cumulative completions catch up to current arrivals.
+        When the cursor is near the right edge and that point falls outside the visible date range,
+        CT and TP cannot be calculated and are hidden; only WIP is shown.
+      </div>
+      <div class="p">
+        See also: This article on <a href="https://blog.mikebowler.ca/2026/03/27/cumulative-flow-diagram/">how to read a CFD</a>.
+      </div>      
+    HTML
+    instance_eval(&block)
+  end
+
+  def column_rules &block
+    @column_rules_block = block
+  end
+
+  def triangle_color color
+    @triangle_color = parse_theme_color(color)
+  end
+
+  def arrival_rate_line_color color
+    @arrival_rate_line_color = parse_theme_color(color)
+  end
+
+  def departure_rate_line_color color
+    @departure_rate_line_color = parse_theme_color(color)
+  end
+
+  def run
+    all_columns = current_board.visible_columns
+
+    column_rules_list = all_columns.map do |column|
+      rules = CfdColumnRules.new
+      @column_rules_block&.call(column, rules)
+      rules
+    end
+
+    active_pairs   = all_columns.zip(column_rules_list).reject { |_, rules| rules.ignored? }
+    active_columns = active_pairs.map(&:first)
+    active_rules   = active_pairs.map(&:last)
+
+    cfd = CfdDataBuilder.new(
+      board: current_board,
+      issues: issues,
+      date_range: date_range,
+      columns: active_columns
+    ).run
+
+    columns            = cfd[:columns]
+    daily_counts       = cfd[:daily_counts]
+    correction_windows = cfd[:correction_windows]
+    column_count       = columns.size
+
+    # Convert cumulative totals to marginal band heights for Chart.js stacking.
+    # cumulative[i] = issues that reached column i or further.
+    # marginal[i]   = cumulative[i] - cumulative[i+1]  (last column: marginal = cumulative)
+    daily_marginals = daily_counts.transform_values do |cumulative|
+      cumulative.each_with_index.map do |count, i|
+        i < column_count - 1 ? count - cumulative[i + 1] : count
+      end
+    end
+
+    border_colors = active_rules.map { |rules| rules.color || random_color }
+
+    fill_colors = active_rules.zip(border_colors).map { |rules, border| fill_color_for(rules, border) }
+
+    # Datasets in reversed order: rightmost column first (bottom of stack), leftmost last (top).
+    data_sets = columns.each_with_index.map do |name, col_index|
+      col_windows = correction_windows
+        .select { |w| w[:column_index] == col_index }
+        .map { |w| { start_date: w[:start_date].to_s, end_date: w[:end_date].to_s } }
+
+      {
+        label: active_rules[col_index].label || name,
+        label_hint: active_rules[col_index].label_hint,
+        data: date_range.map { |date| { x: date.to_s, y: daily_marginals[date][col_index] } },
+        backgroundColor: fill_colors[col_index],
+        borderColor: border_colors[col_index],
+        fill: true,
+        tension: 0,
+        segment: Segment.new(col_windows)
+      }
+    end.reverse
+
+    # Correction windows for the afterDraw hatch plugin, with dataset index in
+    # Chart.js dataset array (reversed: done column = index 0).
+    hatch_windows = correction_windows.map do |w|
+      {
+        dataset_index: column_count - 1 - w[:column_index],
+        start_date: w[:start_date].to_s,
+        end_date: w[:end_date].to_s,
+        color: border_colors[w[:column_index]],
+        fill_color: fill_colors[w[:column_index]]
+      }
+    end
+
+    @triangle_color = parse_theme_color(['#333333', '#ffffff']) unless instance_variable_defined?(:@triangle_color)
+    unless instance_variable_defined?(:@arrival_rate_line_color)
+      @arrival_rate_line_color = 'rgba(255,138,101,0.85)'
+    end
+    unless instance_variable_defined?(:@departure_rate_line_color)
+      @departure_rate_line_color = 'rgba(128,203,196,0.85)'
+    end
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  private
+
+  def parse_theme_color color
+    return color unless color.is_a?(Array)
+
+    raise ArgumentError, 'Color pair must have exactly two elements: [light_color, dark_color]' unless color.size == 2
+    raise ArgumentError, 'Color pair elements must be strings' unless color.all?(String)
+
+    if color.any? { |c| c.start_with?('--') }
+      raise ArgumentError,
+        'CSS variable references are not supported as color pair elements; use a literal color value instead'
+    end
+
+    light, dark = color
+    RawJavascript.new(
+      "(document.documentElement.dataset.theme === 'dark' || " \
+      '(!document.documentElement.dataset.theme && ' \
+      "window.matchMedia('(prefers-color-scheme: dark)').matches)) " \
+      "? #{dark.to_json} : #{light.to_json}"
+    )
+  end
+
+  def hex_to_rgba hex, alpha
+    r, g, b = hex.delete_prefix('#').scan(/../).map { |c| c.to_i(16) }
+    "rgba(#{r}, #{g}, #{b}, #{alpha})"
+  end
+
+  def fill_color_for rules, border
+    if rules.color.nil? || rules.color.match?(/\A#[0-9a-fA-F]{6}\z/)
+      hex_to_rgba(border, 0.35)
+    else
+      rules.color
+    end
+  end
+end