jirametrics 2.20.1 → 2.25

data/lib/jirametrics/css_variable.rb

@@ -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,200 @@
+# 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>
+    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

data/lib/jirametrics/{cycletime_config.rb → cycle_time_config.rb}

@@ -6,15 +6,13 @@ require 'date'
 class CycleTimeConfig
   include SelfOrIssueDispatcher
 
-  attr_reader :label, :parent_config, :settings, :file_system
+  attr_reader :label, :settings, :file_system
 
-  def initialize parent_config:, label:, block:, settings:, file_system: nil, today: Date.today
-
-    @parent_config = parent_config
+  def initialize possible_statuses:, label:, block:, settings:, file_system: nil, today: Date.today
+    @possible_statuses = possible_statuses
     @label = label
     @today = today
     @settings = settings
-    @cache_cycletime_calculations = settings['cache_cycletime_calculations']
 
     # If we hit something deprecated and this is nil then we'll blow up. Although it's ugly, this
     # may make it easier to find problems in the test code ;-)
@@ -68,7 +66,7 @@ class CycleTimeConfig
   def started_stopped_changes issue
     cache_key = "#{issue.key}:#{issue.board.id}"
     last_result = (@cache ||= {})[cache_key]
-    return *last_result if last_result && @cache_cycletime_calculations
+    return *last_result if last_result && settings['cache_cycletime_calculations']
 
     started = @start_at.call(issue)
     stopped = @stop_at.call(issue)

data/lib/jirametrics/cycletime_histogram.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
-require 'jirametrics/groupable_issue_chart'
+require 'jirametrics/time_based_histogram'
 
-class CycletimeHistogram < ChartBase
-  include GroupableIssueChart
+class CycletimeHistogram < TimeBasedHistogram
   attr_accessor :possible_statuses
-  attr_reader :show_stats
 
   def initialize block
     super()
 
-    percentiles [50, 85, 98]
-    @show_stats = true
+    @x_axis_title = 'Cycletime in days'
+    @y_axis_title = 'Count'
 
     header_text 'Cycletime Histogram'
     description_text <<-HTML
@@ -30,112 +28,26 @@ class CycletimeHistogram < ChartBase
     end
   end
 
-  def percentiles percs = nil
-    @percentiles = percs unless percs.nil?
-    @percentiles
-  end
-
-  def disable_stats
-    @show_stats = false
-  end
-
-  def run
+  def all_items
     stopped_issues = completed_issues_in_range include_unstarted: true
 
     # For the histogram, we only want to consider items that have both a start and a stop time.
-    histogram_issues = stopped_issues.select { |issue| issue.board.cycletime.started_stopped_times(issue).first }
-    rules_to_issues = group_issues histogram_issues
-
-    the_stats = {}
-
-    overall_stats = stats_for histogram_data: histogram_data_for(issues: histogram_issues), percentiles: @percentiles
-    the_stats[:all] = overall_stats
-    data_sets = rules_to_issues.keys.collect do |rules|
-      the_issue_type = rules.label
-      the_histogram = histogram_data_for(issues: rules_to_issues[rules])
-      the_stats[the_issue_type] = stats_for histogram_data: the_histogram, percentiles: @percentiles if @show_stats
-
-      data_set_for(
-        histogram_data: the_histogram,
-        label: the_issue_type,
-        color: rules.color
-      )
-    end
-
-    if data_sets.empty?
-      return "<h1 class='foldable'>#{@header_text}</h1><div>No data matched the selected criteria. Nothing to show.</div>"
-    end
-
-    wrap_and_render(binding, __FILE__)
+    stopped_issues.select { |issue| issue.started_stopped_times.first }
   end
 
-  def histogram_data_for issues:
-    count_hash = {}
-    issues.each do |issue|
-      days = issue.board.cycletime.cycletime(issue)
-      count_hash[days] = (count_hash[days] || 0) + 1 if days.positive?
-    end
-    count_hash
+  def value_for_item issue
+    issue.board.cycletime.cycletime(issue)
   end
 
-  def stats_for histogram_data:, percentiles:
-    return {} if histogram_data.empty?
-
-    total_values = histogram_data.values.sum
-
-    # Calculate the average
-    weighted_sum = histogram_data.reduce(0) { |sum, (value, frequency)| sum + (value * frequency) }
-    average = total_values.zero? ? 0 : weighted_sum.to_f / total_values
-
-    # Find the mode (or modes!) and the spread of the distribution
-    sorted_histogram = histogram_data.sort_by { |_value, frequency| frequency }
-    max_freq = sorted_histogram[-1][1]
-    mode = sorted_histogram.select { |_v, f| f == max_freq }
-
-    minmax = histogram_data.keys.minmax
-
-    # Calculate percentiles
-    sorted_values = histogram_data.keys.sort
-    cumulative_counts = {}
-    cumulative_sum = 0
-
-    sorted_values.each do |value|
-      cumulative_sum += histogram_data[value]
-      cumulative_counts[value] = cumulative_sum
-    end
-
-    percentile_results = {}
-    percentiles.each do |percentile|
-      rank = (percentile / 100.0) * total_values
-      percentile_value = sorted_values.find { |value| cumulative_counts[value] >= rank }
-      percentile_results[percentile] = percentile_value
-    end
-
-    {
-      average: average,
-      mode: mode.collect(&:first).sort,
-      min: minmax[0],
-      max: minmax[1],
-      percentiles: percentile_results
-    }
+  def title_for_item count:, value:
+    "#{count} items completed in #{label_days value}"
   end
 
-  def data_set_for histogram_data:, label:, color:
-    keys = histogram_data.keys.sort
-    {
-      type: 'bar',
-      label: label,
-      data: keys.sort.filter_map do |key|
-        next if histogram_data[key].zero?
+  def sort_items items
+    items.sort_by(&:key_as_i)
+  end
 
-        {
-          x: key,
-          y: histogram_data[key],
-          title: "#{histogram_data[key]} items completed in #{label_days key}"
-        }
-      end,
-      backgroundColor: color,
-      borderRadius: 0
-    }
+  def label_for_item issue, hint:
+    "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
   end
 end

data/lib/jirametrics/cycletime_scatterplot.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
-require 'jirametrics/groupable_issue_chart'
-
-class CycletimeScatterplot < ChartBase
-  include GroupableIssueChart
+require 'jirametrics/time_based_scatterplot'
 
+class CycletimeScatterplot < TimeBasedScatterplot
   attr_accessor :possible_statuses
 
   def initialize block
@@ -26,6 +24,8 @@ class CycletimeScatterplot < ChartBase
       </div>
       #{describe_non_working_days}
     HTML
+    @x_axis_title = 'Date completed'
+    @y_axis_title = 'Cycletime in days'
 
     init_configuration_block block do
       grouping_rules do |issue, rule|
@@ -33,95 +33,25 @@ class CycletimeScatterplot < ChartBase
         rule.color = color_for type: issue.type
       end
     end
-
-    @percentage_lines = []
-    @highest_cycletime = 0
   end
 
-  def run
-    completed_issues = completed_issues_in_range include_unstarted: false
-
-    data_sets = create_datasets completed_issues
-    overall_percent_line = calculate_percent_line(completed_issues)
-    @percentage_lines << [overall_percent_line, CssVariable['--cycletime-scatterplot-overall-trendline-color']]
-
-    return "<h1>#{@header_text}</h1>No data matched the selected criteria. Nothing to show." if data_sets.empty?
-
-    wrap_and_render(binding, __FILE__)
-  end
-
-  def create_datasets completed_issues
-    data_sets = []
-
-    group_issues(completed_issues).each do |rules, completed_issues_by_type|
-      label = rules.label
-      color = rules.color
-      percent_line = calculate_percent_line completed_issues_by_type
-      data = completed_issues_by_type.filter_map { |issue| data_for_issue(issue) }
-      data_sets << {
-        label: "#{label} (85% at #{label_days(percent_line)})",
-        data: data,
-        fill: false,
-        showLine: false,
-        backgroundColor: color
-      }
-
-      data_sets << trend_line_data_set(label: label, data: data, color: color)
-
-      @percentage_lines << [percent_line, color]
-    end
-    data_sets
+  def all_items
+    completed_issues_in_range include_unstarted: false
   end
 
-  def show_trend_lines
-    @show_trend_lines = true
+  def x_value item
+    item.started_stopped_times.last
   end
 
-  def trend_line_data_set label:, data:, color:
-    points = data.collect do |hash|
-      [Time.parse(hash[:x]).to_i, hash[:y]]
-    end
-
-    # The trend calculation works with numbers only so convert Time to an int and back
-    calculator = TrendLineCalculator.new(points)
-    data_points = calculator.chart_datapoints(
-      range: time_range.begin.to_i..time_range.end.to_i,
-      max_y: @highest_cycletime
-    )
-    data_points.each do |point_hash|
-      point_hash[:x] = chart_format Time.at(point_hash[:x])
-    end
-
-    {
-      type: 'line',
-      label: "#{label} Trendline",
-      data: data_points,
-      fill: false,
-      borderWidth: 1,
-      markerType: 'none',
-      borderColor: color,
-      borderDash: [6, 3],
-      pointStyle: 'dash',
-      hidden: !@show_trend_lines
-    }
+  def y_value item
+    item.board.cycletime.cycletime(item)
   end
 
-  def data_for_issue issue
-    cycle_time = issue.board.cycletime.cycletime(issue)
-    return nil if cycle_time < 1 # These will get called out on the quality report
-
-    @highest_cycletime = cycle_time if @highest_cycletime < cycle_time
-
-    {
-      y: cycle_time,
-      x: chart_format(issue.board.cycletime.started_stopped_times(issue).last),
-      title: ["#{issue.key} : #{issue.summary} (#{label_days(cycle_time)})"]
-    }
+  def title_value item, rules: nil
+    hint = @issue_hints&.fetch(item, nil)
+    "#{item.key} : #{item.summary} (#{label_days(y_value(item))})#{" #{hint}" if hint}"
   end
 
-  def calculate_percent_line completed_issues
-    times = completed_issues.collect { |issue| issue.board.cycletime.cycletime(issue) }
-    index = times.size * 85 / 100
-    times.sort[index]
-  end
+  # Kept for backwards compatibility with existing callers and specs
+  alias data_for_issue data_for_item
 end

data/lib/jirametrics/daily_view.rb

@@ -9,7 +9,8 @@ class DailyView < ChartBase
     header_text 'Daily View'
     description_text <<-HTML
       <div class="p">
-        This view shows all the items you'll want to discuss during your daily coordination meeting
+        This view shows all the items (<%= aging_issues.count %>) you'll want to discuss during your daily
+        coordination meeting
         (aka daily scrum, standup), in the order that you should be discussing them. The most important
         items are at the top, and the least at the bottom.
       </div>
@@ -35,7 +36,7 @@ class DailyView < ChartBase
 
   def select_aging_issues
     aging_issues = issues.select do |issue|
-      started_at, stopped_at = issue.board.cycletime.started_stopped_times(issue)
+      started_at, stopped_at = issue.started_stopped_times
       started_at && !stopped_at
     end
 
@@ -72,7 +73,7 @@ class DailyView < ChartBase
 
   def make_blocked_stalled_lines issue
     today = date_range.end
-    started_date = issue.board.cycletime.started_stopped_times(issue).first&.to_date
+    started_date = issue.started_stopped_times.first&.to_date
     return [] unless started_date
 
     blocked_stalled = issue.blocked_stalled_by_date(
@@ -86,9 +87,14 @@ class DailyView < ChartBase
       lines << ["#{marker} Blocked by flag"] if blocked_stalled.flag
       lines << ["#{marker} Blocked by status: #{blocked_stalled.status}"] if blocked_stalled.blocked_by_status?
       blocked_stalled.blocking_issue_keys&.each do |key|
-        lines << ["#{marker} Blocked by issue: #{key}"]
         blocking_issue = issues.find { |i| i.key == key }
-        lines << blocking_issue if blocking_issue
+        if blocking_issue
+          lines << "<section><div class=\"foldable startFolded\">#{marker} Blocked by issue: #{key}</div>"
+          lines << blocking_issue
+          lines << '</section>'
+        else
+          lines << ["#{marker} Blocked by issue: #{key}"]
+        end
       end
     elsif blocked_stalled.stalled_by_status?
       lines << ["#{color_block '--stalled-color'} Stalled by status: #{blocked_stalled.status}"]
@@ -146,7 +152,18 @@ class DailyView < ChartBase
       line << "Assignee: <img src='#{issue.assigned_to_icon_url}' class='icon' /> <b>#{issue.assigned_to}</b>"
     end
 
-    line << "Due: <b>#{issue.due_date}</b>" if issue.due_date
+    if issue.due_date
+      today = date_range.end
+      days = (issue.due_date - today).to_i
+      relative =
+        if days.zero? then 'today'
+        elsif days.positive? then "in #{label_days days}"
+        else "#{label_days(-days)} ago"
+        end
+      content = "#{issue.due_date} (#{relative})"
+      content = "<span style='background: var(--warning-banner)'>#{content}</span>" if days.negative?
+      line << "Due: <b>#{content}</b>"
+    end
 
     block = lambda do |collection, label|
       unless collection.empty?
@@ -166,7 +183,7 @@ class DailyView < ChartBase
 
     return lines if subtasks.empty?
 
-    lines << '<section><div class="foldable">Child issues</div>'
+    lines << "<section><div class=\"foldable startFolded\">Child issues (#{subtasks.count})</div>"
     lines += subtasks
     lines << '</section>'
 
@@ -237,9 +254,11 @@ class DailyView < ChartBase
 
   def make_description_lines issue
     description = issue.raw['fields']['description']
-    result = []
-    result << [atlassian_document_format.to_html(description)] if description
-    result
+    return [] unless description
+
+    text = "<div class='foldable startFolded'>Description</div>" \
+           "<div>#{atlassian_document_format.to_html(description)}</div>"
+    [[text]]
   end
 
   def assemble_issue_lines issue, child:
@@ -247,6 +266,7 @@ class DailyView < ChartBase
 
     lines = []
     lines << [make_title_line(issue: issue, done: done)]
+    lines << make_not_visible_line(issue)
     lines += make_parent_lines(issue) unless child
     lines += make_stats_lines(issue: issue, done: done)
     unless done
@@ -256,7 +276,7 @@ class DailyView < ChartBase
       lines += make_child_lines(issue)
       lines += make_history_lines(issue)
     end
-    lines
+    lines.compact
   end
 
   def render_issue issue, child:
@@ -278,4 +298,8 @@ class DailyView < ChartBase
     end
     result << '</div>'
   end
+
+  def make_not_visible_line issue
+    not_visible_text issue
+  end
 end

data/lib/jirametrics/daily_wip_by_age_chart.rb

@@ -49,9 +49,7 @@ class DailyWipByAgeChart < DailyWipChart
   end
 
   def default_grouping_rules issue:, rules:
-    started, stopped = issue.board.cycletime.started_stopped_dates(issue)
-
-    rules.issue_hint = "(age: #{label_days (rules.current_date - started + 1).to_i})" if started
+    started, stopped = issue.started_stopped_dates
 
     if stopped && started.nil? # We can't tell when it started
       @has_completed_but_not_started = true
@@ -72,7 +70,7 @@ class DailyWipByAgeChart < DailyWipChart
       rules.label = 'Start date unknown'
       rules.color = '--body-background'
       rules.group_priority = 11
-      created_days = rules.current_date - created + 1
+      created_days = rules.current_date - created
       rules.issue_hint = "(created: #{label_days created_days.to_i} earlier, stopped on #{stopped})"
     end
   end
@@ -84,7 +82,8 @@ class DailyWipByAgeChart < DailyWipChart
   end
 
   def group_by_age started:, rules:
-    age = rules.current_date - started + 1
+    age = (rules.current_date - started).to_i + 1
+    rules.issue_hint = "(age: #{label_days age})"
 
     case age
     when 1