jirametrics 2.31 → 3.1

data/lib/jirametrics/stitcher.rb

@@ -32,8 +32,8 @@ class Stitcher < HtmlGenerator
   end
 
   def make_output_filename input_filename
-    if /^(.+)\.erb$/ =~ input_filename
-      "#{$1}.html"
+    if /^(?<base_name>.+)\.erb$/ =~ input_filename
+      "#{base_name}.html"
     else
       "#{input_filename}.html"
     end
@@ -48,7 +48,8 @@ class Stitcher < HtmlGenerator
     ''
   end
 
-  def parse_file filename
+  # Imperative: it parses the file. The boolean is a "was it newly parsed" status, not a question.
+  def parse_file filename # rubocop:disable Naming/PredicateMethod
     return false if @loaded_files.include? filename
 
     # To match: <!-- seam-start | chart78 | GithubPrScatterplot | PR Scatterplot | chart -->
@@ -57,19 +58,7 @@ class Stitcher < HtmlGenerator
     file_system.load(filename).lines do |line|
       matches = line.match(regex)
       if matches
-        if matches[:seam] == 'start'
-          content = +''
-        else
-          if content.nil? || content.strip.empty?
-            file_system.warning "Seam found with no content in #{filename.inspect}: " \
-              "id=#{matches[:id].strip.inspect}, class=#{matches[:clazz].strip.inspect}, " \
-              "title=#{matches[:title].strip.inspect}"
-          end
-          @all_stitches << Stitcher::StitchContent.new(
-            file: filename, title: matches[:title], type: matches[:type], content: content
-          )
-          content = nil
-        end
+        content = handle_seam matches, filename: filename, content: content
       elsif content
         content << line
       end
@@ -78,4 +67,20 @@ class Stitcher < HtmlGenerator
     @loaded_files << filename
     true
   end
+
+  # Handle one seam marker line, returning the new accumulator state: a fresh buffer for a start
+  # seam, or nil for an end seam (after recording the content collected since the start).
+  def handle_seam matches, filename:, content:
+    return +'' if matches[:seam] == 'start'
+
+    if content.nil? || content.strip.empty?
+      file_system.warning "Seam found with no content in #{filename.inspect}: " \
+        "id=#{matches[:id].strip.inspect}, class=#{matches[:clazz].strip.inspect}, " \
+        "title=#{matches[:title].strip.inspect}"
+    end
+    @all_stitches << Stitcher::StitchContent.new(
+      file: filename, title: matches[:title], type: matches[:type], content: content
+    )
+    nil
+  end
 end

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
@@ -17,7 +18,7 @@ class WipByColumnChart < ChartBase
       <p>
         Each row on the Y axis is a WIP level (the number of items in that column at the same time).
         Each column on the X axis is a board column.
-        The horizontal bars show what percentage of the total time that column spent at that WIP level —
+        The horizontal bars show what percentage of the total time that column spent at that WIP level -
         a wider bar means more time was spent there.
       </p>
       <p>
@@ -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
@@ -135,7 +136,7 @@ class WipByColumnChart < ChartBase
 
       max = @wip_limits[i]['max']
       if max.nil?
-        "Add a WIP limit to column '#{name}' — suggested maximum: #{rec}"
+        "Add a WIP limit to column '#{name}' - suggested maximum: #{rec}"
       elsif rec < max
         "Lower the WIP limit for '#{name}' from #{max} to #{rec}"
       elsif rec > max
@@ -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

@@ -46,6 +46,23 @@ class JiraMetrics < Thor
     Exporter.instance.export(name_filter: options[:name] || '*')
   end
 
+  option :config
+  option :name
+  desc 'verify', 'Check that JiraMetrics can authenticate to Jira, without downloading anything'
+  def verify
+    load_config options[:config]
+    results = Exporter.instance.verify_jira_connections(name_filter: options[:name] || '*')
+    exit 1 if results.empty? || results.any? { |result| !result.ok }
+  end
+
+  option :config
+  option :name
+  desc 'boards', "Show a board's columns and statuses, to help choose cycletime start/stop points"
+  def boards board_id = nil
+    load_config options[:config]
+    exit 1 unless Exporter.instance.boards(board_id: board_id, name_filter: options[:name])
+  end
+
   option :config
   desc 'info', 'Dump information about one issue'
   def info key
@@ -63,7 +80,9 @@ class JiraMetrics < Thor
     original_stdout = $stdout.dup
     $stdout.reopen($stderr)
 
-    load_config options[:config]
+    # Log to a separate file so that starting the MCP server doesn't truncate jirametrics.log, which
+    # someone may be relying on to debug a preceding export run.
+    load_config options[:config], logfile_name: 'jirametrics-mcp.log'
     require 'jirametrics/mcp_server'
 
     Exporter.instance.file_system.log_only = true
@@ -78,6 +97,10 @@ class JiraMetrics < Thor
         today: project.time_range.end.to_date,
         end_time: project.time_range.end
       }
+      # Fabrication is lazy, so force every historical status to resolve now and then emit the single
+      # consolidated warning into jirametrics-mcp.log (file_system is log_only here).
+      project.resolve_all_status_changes
+      project.report_fabricated_statuses
     rescue StandardError => e
       if e.message.start_with? 'This is an aggregated project'
         names = project.aggregate_project_names
@@ -108,17 +131,21 @@ 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
-    def load_config config_file, file_system: FileSystem.new
+    def load_config config_file, logfile_name: nil, file_system: FileSystem.new
       config_file = './config.rb' if config_file.nil?
 
       if file_system.file_exist? config_file
@@ -131,6 +158,10 @@ class JiraMetrics < Thor
       end
 
       require_rel 'jirametrics'
+      # Set only after the require above, so Exporter is defined. The config file we load below calls
+      # Exporter.configure, which opens this log; the MCP server passes its own name so it doesn't
+      # truncate jirametrics.log.
+      Exporter.logfile_name = logfile_name if logfile_name
       load config_file
     end
   end