jirametrics 2.31 → 3.0

data/lib/jirametrics/throughput_chart.rb

@@ -7,8 +7,10 @@ class ThroughputChart < ChartBase
 
   attr_accessor :possible_statuses
 
-  def initialize block
+  def initialize block, throughput_samples: nil, not_started_count: nil
     super()
+    @throughput_samples = throughput_samples
+    @not_started_count = not_started_count
 
     header_text 'Throughput Chart'
     description_text <<-TEXT
@@ -120,30 +122,42 @@ class ThroughputChart < ChartBase
   def throughput_dataset periods:, completed_issues:, label_hint: nil
     custom_mode = @issue_periods&.values&.any?
     periods.collect do |period|
-      closed_issues = completed_issues.filter_map do |issue|
-        stop_date = issue.started_stopped_dates.last
-        next unless stop_date
-
-        if custom_mode
-          [stop_date, issue] if @issue_periods[issue] == period.end
-        elsif period.include?(stop_date)
-          [stop_date, issue]
-        end
-      end
+      closed_issues = closed_issues_in_period(period, completed_issues, custom_mode)
+      period_dataset(period: period, closed_issues: closed_issues, label_hint: label_hint)
+    end
+  end
+
+  def closed_issues_in_period period, completed_issues, custom_mode
+    completed_issues.filter_map do |issue|
+      stop_date = issue.started_stopped_dates.last
+      next unless stop_date
 
-      date_label = "on #{period.end}"
-      date_label = "between #{period.begin} and #{period.end}" unless period.begin == period.end
-
-      with_label_hint = label_hint ? " with #{label_hint}" : ''
-      {
-        y: closed_issues.size,
-        x: "#{period.end}T23:59:59",
-        title: ["#{closed_issues.size} items closed#{with_label_hint} #{date_label}"] +
-          closed_issues.collect do |_stop_date, issue|
-            hint = @issue_hints&.fetch(issue, nil)
-            "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
-          end
-      }
+      if custom_mode
+        issue if @issue_periods[issue] == period.end
+      elsif period.include?(stop_date)
+        issue
+      end
     end
   end
+
+  def period_dataset period:, closed_issues:, label_hint:
+    label_hint_text = label_hint ? " with #{label_hint}" : ''
+    header = "#{closed_issues.size} items closed#{label_hint_text} #{period_label(period)}"
+    {
+      y: closed_issues.size,
+      x: "#{period.end}T23:59:59",
+      title: [header] + closed_issues.collect { |issue| issue_title_line(issue) }
+    }
+  end
+
+  def period_label period
+    return "on #{period.end}" if period.begin == period.end
+
+    "between #{period.begin} and #{period.end}"
+  end
+
+  def issue_title_line issue
+    hint = @issue_hints&.fetch(issue, nil)
+    "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
+  end
 end

data/lib/jirametrics/time_based_chart.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'jirametrics/chart_base'
+
+# Common base for every cycle-time chart. It owns the cycletime *unit system* --
+# which unit the value axis is expressed in and how a raw value is labelled --
+# because that concern is core to any chart that plots a cycle time, not a
+# cross-cutting add-on. The scatter/histo split lives one level down (in
+# TimeBasedScatterplot / TimeBasedHistogram, which supply the value_axis_title=
+# hook so this class doesn't need to know which axis carries the value); the
+# PR-vs-issue split lives one level below that.
+class TimeBasedChart < ChartBase
+  # The cycletime units we support, mapped to how each reads in an axis title.
+  # :days counts calendar days; :hours24 counts elapsed 24-hour clock periods
+  # (the two differ for anything that crosses midnight).
+  VALUE_AXIS_LABELS = {
+    minutes: 'minutes',
+    hours: 'hours',
+    days: 'days',
+    hours24: '24-hour periods'
+  }.freeze
+
+  def initialize
+    super
+
+    @cycletime_unit = :days
+  end
+
+  def cycletime_unit unit
+    axis_label = VALUE_AXIS_LABELS[unit]
+    unless axis_label
+      raise ArgumentError,
+        "cycletime_unit must be one of #{VALUE_AXIS_LABELS.keys.map(&:inspect).join(', ')}, got #{unit.inspect}"
+    end
+
+    @cycletime_unit = unit
+    self.value_axis_title = "Cycle time in #{axis_label}"
+  end
+
+  def label_cycletime value
+    case @cycletime_unit
+    when :minutes then label_minutes(value)
+    when :hours then label_hours(value)
+    when :days then label_days(value)
+    when :hours24 then "#{value}x 24h periods"
+    end
+  end
+
+  # Converts the span between two Times into the selected cycletime unit.
+  #
+  # :days is deliberately different from the other units: it counts calendar days
+  # inclusively in the configured timezone (opened and closed on the same day is
+  # 1 day, crossing one midnight is 2), matching the working-days cycletime engine.
+  # The elapsed units (:hours, :minutes) divide the wall-clock span and round up --
+  # a partial unit still counts as one, so a 20-minute PR is 1 hour, never 0.
+  def duration_in_unit from, to
+    if @cycletime_unit == :days
+      tz = timezone_offset || '+00:00'
+      (to.getlocal(tz).to_date - from.getlocal(tz).to_date).to_i + 1
+    else
+      seconds_per_unit = { minutes: 60, hours: 3600, hours24: 86_400 }[@cycletime_unit]
+      ((to - from) / seconds_per_unit).ceil
+    end
+  end
+end

data/lib/jirametrics/time_based_histogram.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require 'jirametrics/groupable_issue_chart'
+require 'jirametrics/time_based_chart'
 
-class TimeBasedHistogram < ChartBase
+class TimeBasedHistogram < TimeBasedChart
   include GroupableIssueChart
 
   attr_reader :show_stats
@@ -14,6 +15,11 @@ class TimeBasedHistogram < ChartBase
     @show_stats = true
   end
 
+  # On a histogram the cycle time is plotted along the x-axis (count is on the y-axis).
+  def value_axis_title= title
+    @x_axis_title = title
+  end
+
   def percentiles percs = nil
     @percentiles = percs unless percs.nil?
     @percentiles
@@ -68,42 +74,43 @@ class TimeBasedHistogram < ChartBase
     return {} if histogram_data.empty?
 
     total_values = histogram_data.values.sum
+    min, max = histogram_data.keys.minmax
+    {
+      average: average_for(histogram_data, total_values),
+      mode: modes_for(histogram_data),
+      min: min,
+      max: max,
+      percentiles: percentiles_for(histogram_data, percentiles, total_values)
+    }
+  end
 
-    # 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
+  def average_for histogram_data, total_values
+    return 0 if total_values.zero?
 
-    # 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 }
+    weighted_sum = histogram_data.reduce(0) { |sum, (value, frequency)| sum + (value * frequency) }
+    weighted_sum.to_f / total_values
+  end
 
-    minmax = histogram_data.keys.minmax
+  # Every value that ties for the highest frequency, so a flat or multi-modal distribution returns them all.
+  def modes_for histogram_data
+    sorted_by_frequency = histogram_data.sort_by { |_value, frequency| frequency }
+    max_frequency = sorted_by_frequency[-1][1]
+    sorted_by_frequency.select { |_value, frequency| frequency == max_frequency }.collect(&:first).sort
+  end
 
-    # Calculate percentiles
+  def percentiles_for histogram_data, percentiles, total_values
     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|
+    percentiles.to_h do |percentile|
       rank = (percentile / 100.0) * total_values
-      percentile_value = sorted_values.find { |value| cumulative_counts[value] >= rank }
-      percentile_results[percentile] = percentile_value
+      [percentile, sorted_values.find { |value| cumulative_counts[value] >= rank }]
     end
-
-    {
-      average: average,
-      mode: mode.collect(&:first).sort,
-      min: minmax[0],
-      max: minmax[1],
-      percentiles: percentile_results
-    }
   end
 
   def sort_items items

data/lib/jirametrics/time_based_scatterplot.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require 'jirametrics/groupable_issue_chart'
+require 'jirametrics/time_based_chart'
 
-class TimeBasedScatterplot < ChartBase
+class TimeBasedScatterplot < TimeBasedChart
   include GroupableIssueChart
 
   def initialize
@@ -12,13 +13,21 @@ class TimeBasedScatterplot < ChartBase
     @highest_y_value = 0
   end
 
+  # On a scatterplot the cycle time is plotted up the y-axis.
+  def value_axis_title= title
+    @y_axis_title = title
+  end
+
   def run
     items = all_items
     data_sets = create_datasets items
     overall_percent_line = calculate_percent_line(items)
     @percentage_lines << [overall_percent_line, CssVariable['--cycletime-scatterplot-overall-trendline-color']]
 
-    return "<h1 class='foldable'>#{@header_text}</h1><div>No data matched the selected criteria. Nothing to show.</div>" if data_sets.empty?
+    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__)
   end

data/lib/jirametrics/trend_line_calculator.rb

@@ -24,11 +24,11 @@ class TrendLineCalculator
   def horizontal? = @slope.zero?
   def vertical? = @slope.nan? || @slope.infinite?
 
-  def calc_y x: # rubocop:disable Naming/MethodParameterName
+  def calc_y x:
     ((x * @slope) + @offset).to_i
   end
 
-  def line_crosses_at y: # rubocop:disable Naming/MethodParameterName
+  def line_crosses_at y:
     raise "line will never cross #{y}. Trend is perfectly horizontal" if horizontal?
 
     ((y.to_f - @offset) / @slope).to_i

data/lib/jirametrics/wip_by_column_chart.rb

@@ -7,7 +7,8 @@ class WipByColumnChart < ChartBase
 
   ColumnStats = Struct.new(:name, :min_wip_limit, :max_wip_limit, :wip_history, keyword_init: true)
 
-  def initialize block
+  # Long only because of the inline description_text heredoc and one-time setup; splitting wouldn't help.
+  def initialize block # rubocop:disable Metrics/MethodLength
     super()
     header_text 'WIP by column'
     description_text <<-HTML
@@ -64,10 +65,10 @@ class WipByColumnChart < ChartBase
       total = stat.wip_history.sum { |_wip, seconds| seconds }.to_f
       next [] if total.zero?
 
-      stat.wip_history.collect { |wip, seconds| { 'wip' => wip, 'pct' => format_pct(seconds, total) } }
+      wip_percentages(stat.wip_history, total)
     end
-    @max_wip = stats.flat_map { |s| s.wip_history.collect { |wip, _| wip } }.max || 0
-    @wip_limits = stats.collect { |s| { 'min' => s.min_wip_limit, 'max' => s.max_wip_limit } }
+    @max_wip = max_wip_level(stats)
+    @wip_limits = wip_limits(stats)
     @recommendations = @show_recommendations ? compute_recommendations(stats) : Array.new(stats.size)
 
     trim_zero_end_columns
@@ -144,6 +145,22 @@ class WipByColumnChart < ChartBase
     end
   end
 
+  # Turn a column's WIP history into render rows: each WIP level with the percentage of the column's
+  # total time spent there.
+  def wip_percentages wip_history, total
+    wip_history.collect { |wip, seconds| { 'wip' => wip, 'pct' => format_pct(seconds, total) } }
+  end
+
+  # The highest WIP level reached in any column, or 0 when there's no data.
+  def max_wip_level stats
+    stats.flat_map { |stat| stat.wip_history.collect { |wip, _seconds| wip } }.max || 0
+  end
+
+  # The configured min/max WIP limits for each column, in column order.
+  def wip_limits stats
+    stats.collect { |stat| { 'min' => stat.min_wip_limit, 'max' => stat.max_wip_limit } }
+  end
+
   def format_pct seconds, total
     raw = seconds / total * 100.0
     (1..10).each do |decimals|
@@ -173,8 +190,7 @@ class WipByColumnChart < ChartBase
         next
       end
 
-      last_change = issue.status_changes.reverse.find { |c| c.time <= time_range.begin }
-      hash[issue] = last_change ? status_to_column[last_change.value_id] : nil
+      hash[issue] = column_as_of(issue, time_range.begin, status_to_column)
     end
   end
 
@@ -184,30 +200,46 @@ class WipByColumnChart < ChartBase
       started_time, stopped_time = issue.board.cycletime.started_stopped_times(issue)
       next unless started_time
 
-      # Issue starts within the window: add an explicit event to enter WIP in its current column
-      if started_time > time_range.begin && started_time <= time_range.end
-        last_change = issue.status_changes.reverse.find { |c| c.time <= started_time }
-        events << [started_time, issue, last_change ? status_to_column[last_change.value_id] : nil]
+      if within_window?(started_time)
+        # add an explicit event to enter WIP in its current column
+        events << [started_time, issue, column_as_of(issue, started_time, status_to_column)]
       end
 
-      # Status changes while the issue is actively in WIP and within the window
       issue.status_changes.each do |change|
-        next unless change.time > time_range.begin
-        next if change.time > time_range.end
-        next unless change.time >= started_time
-        next if stopped_time && change.time >= stopped_time
+        next unless in_wip_and_within_window?(change, started_time, stopped_time)
 
         events << [change.time, issue, status_to_column[change.value_id]]
       end
 
-      # Issue stops within the window: add an explicit event to exit WIP
-      if stopped_time && stopped_time > time_range.begin && stopped_time <= time_range.end
-        events << [stopped_time, issue, nil]
-      end
+      events << [stopped_time, issue, nil] if within_window?(stopped_time)
     end
     events.sort_by!(&:first)
   end
 
+  # True when a (present) time falls inside the chart window: after it opens, up to and including
+  # when it closes.
+  def within_window? time
+    time && time > time_range.begin && time <= time_range.end
+  end
+
+  # A status change counts if it happened inside the window and while the issue was actively in WIP:
+  # after the window opens, up to and including when it closes, at or after the issue started, and
+  # strictly before it stopped.
+  def in_wip_and_within_window? change, started_time, stopped_time
+    return false unless within_window?(change.time)
+    return false unless change.time >= started_time
+    return false if stopped_time && change.time >= stopped_time
+
+    true
+  end
+
+  # The column the issue was displayed in as of the given time: the column of its most recent
+  # status change at or before that time, or nil if it hadn't changed status yet.
+  def column_as_of issue, time, status_to_column
+    last_change = issue.status_changes.reverse.find { |change| change.time <= time }
+    last_change ? status_to_column[last_change.value_id] : nil
+  end
+
   def compute_wip_seconds columns, current_column, events
     wip_counts = Array.new(columns.size, 0)
     current_column.each_value { |col| wip_counts[col] += 1 unless col.nil? }
@@ -216,21 +248,30 @@ class WipByColumnChart < ChartBase
     prev_time = time_range.begin
 
     events.each do |time, issue, new_col|
-      elapsed = (time - prev_time).to_i
-      if elapsed.positive?
-        wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed }
-        prev_time = time
-      end
-
-      old_col = current_column[issue]
-      wip_counts[old_col] -= 1 unless old_col.nil?
-      wip_counts[new_col] += 1 unless new_col.nil?
-      current_column[issue] = new_col
+      prev_time = accumulate_wip_seconds(column_wip_seconds, wip_counts, prev_time, time)
+      apply_event(wip_counts, current_column, issue, new_col)
     end
-
-    elapsed = (time_range.end - prev_time).to_i
-    wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed } if elapsed.positive?
+    accumulate_wip_seconds(column_wip_seconds, wip_counts, prev_time, time_range.end)
 
     column_wip_seconds
   end
+
+  # Attribute the seconds between prev_time and time to each column's current WIP level, then return
+  # the new prev_time. A zero-length gap changes nothing and leaves prev_time where it was.
+  def accumulate_wip_seconds column_wip_seconds, wip_counts, prev_time, time
+    elapsed = (time - prev_time).to_i
+    return prev_time unless elapsed.positive?
+
+    wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed }
+    time
+  end
+
+  # Move the issue out of its old column and into new_col, keeping wip_counts and current_column in
+  # sync. A nil column means the issue isn't on the board — ie entering or leaving WIP.
+  def apply_event wip_counts, current_column, issue, new_col
+    old_col = current_column[issue]
+    wip_counts[old_col] -= 1 unless old_col.nil?
+    wip_counts[new_col] += 1 unless new_col.nil?
+    current_column[issue] = new_col
+  end
 end

data/lib/jirametrics.rb

@@ -108,13 +108,17 @@ class JiraMetrics < Thor
       file_system ||= Exporter.instance.file_system
       return if file_system.logfile == $stdout
 
-      file_system.logfile.puts "#{exception.class}: #{exception.message}"
-      exception.backtrace&.each { |line| file_system.logfile.puts "\t#{line}" }
+      write_exception_to_logfile file_system.logfile, exception
     rescue StandardError
       # Exporter may not be initialized, or the logfile may already be closed
     end
   end
 
+  def self.write_exception_to_logfile logfile, exception
+    logfile.puts "#{exception.class}: #{exception.message}"
+    exception.backtrace&.each { |line| logfile.puts "\t#{line}" }
+  end
+
   at_exit { JiraMetrics.log_uncaught_exception $ERROR_INFO }
 
   no_commands do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '2.31'
+  version: '3.0'
 platform: ruby
 authors:
 - Mike Bowler
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: mutant-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -69,16 +55,16 @@ dependencies:
   name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: '0'
 description: Extract metrics from Jira and export to either a report or to CSV files
 email: mbowler@gargoylesoftware.com
 executables:
@@ -97,7 +83,9 @@ files:
 - lib/jirametrics/anonymizer.rb
 - lib/jirametrics/atlassian_document_format.rb
 - lib/jirametrics/bar_chart_range.rb
+- lib/jirametrics/blocked_stalled_by_date_builder.rb
 - lib/jirametrics/blocked_stalled_change.rb
+- lib/jirametrics/blocked_stalled_change_stream_builder.rb
 - lib/jirametrics/board.rb
 - lib/jirametrics/board_column.rb
 - lib/jirametrics/board_config.rb
@@ -132,6 +120,7 @@ files:
 - lib/jirametrics/file_config.rb
 - lib/jirametrics/file_system.rb
 - lib/jirametrics/fix_version.rb
+- lib/jirametrics/flow_efficiency_calculator.rb
 - lib/jirametrics/flow_efficiency_scatterplot.rb
 - lib/jirametrics/github_gateway.rb
 - lib/jirametrics/groupable_issue_chart.rb
@@ -175,12 +164,16 @@ files:
 - lib/jirametrics/settings.json
 - lib/jirametrics/sprint.rb
 - lib/jirametrics/sprint_burndown.rb
+- lib/jirametrics/sprint_count_measure.rb
 - lib/jirametrics/sprint_issue_change_data.rb
+- lib/jirametrics/sprint_points_measure.rb
+- lib/jirametrics/sprint_summary_stats.rb
 - lib/jirametrics/status.rb
 - lib/jirametrics/status_collection.rb
 - lib/jirametrics/stitcher.rb
 - lib/jirametrics/throughput_by_completed_resolution_chart.rb
 - lib/jirametrics/throughput_chart.rb
+- lib/jirametrics/time_based_chart.rb
 - lib/jirametrics/time_based_histogram.rb
 - lib/jirametrics/time_based_scatterplot.rb
 - lib/jirametrics/tree_organizer.rb
@@ -203,7 +196,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="