jirametrics 2.7.3 → 2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed5733b75d3ab3091973a5919269c467e6657a1a7699a6e5e4acb4139f9a292b
-  data.tar.gz: 3e750fe3a053fe9d8b5c30099afc42d1c50187c1d749f922d29bd91eb2f60241
+  metadata.gz: f5bec8084c47e2383d25676b969891c6fc8e427d06427a1caf195378a830ff4f
+  data.tar.gz: e9364c2b43f66d90a651f50e115751c144f8dfc6f7d247b47dfd17495bdf167e
 SHA512:
-  metadata.gz: 9f97b93668b57a3f5876979daa14631c1f75f6d6294b49ae58f57b2d60e21b36020c64aef8d7affa59e03796e8c7b3e5480546e3a540372d20c3152764d8a6a0
-  data.tar.gz: ed479b302392340ca02a7f58d4ac0e5f27178ff23fc35956ebeb8659af91454ca8d7e752aacbcad3bef942c49bc24f03dca332760b582b23c782cb5824681651
+  metadata.gz: 82c740fa8d23565eb33edf1e244cde1b8b8ef2d88f753091fd0f3cfb7e20aa67c32fc22dca70d4076c25ad40898a0872c13f8af14173a26b33054faf8838df14
+  data.tar.gz: 66d5db7495165aa4ac0ea36acd27e1b77d2d4b4d4ebb7912fbbffee57c9c160b8cee3fc919884564370db51618438d24fc6fde5e47e2343560aca52b53917d4b

data/lib/jirametrics/aggregate_config.rb

@@ -41,7 +41,7 @@ class AggregateConfig
   def include_issues_from project_name
     project = @project_config.exporter.project_configs.find { |p| p.name == project_name }
     if project.nil?
-      log "Warning: Aggregated project #{@project_config.name.inspect} is attempting to load " \
+      file_system.warning "Aggregated project #{@project_config.name.inspect} is attempting to load " \
         "project #{project_name.inspect} but it can't be found. Is it disabled?"
       return
     end
@@ -86,7 +86,7 @@ class AggregateConfig
 
   private
 
-  def log message
-    @project_config.exporter.file_system.log message
+  def file_system
+    @project_config.exporter.file_system
   end
 end

data/lib/jirametrics/aging_work_bar_chart.rb

@@ -116,7 +116,7 @@ class AgingWorkBarChart < ChartBase
     issue.changes.each do |change|
       next unless change.status?
 
-      status = issue.find_status_by_name change.value
+      status = issue.find_status_by_id change.value_id, name: change.value
 
       unless previous_start.nil? || previous_start < issue_started_time
         hash = {

data/lib/jirametrics/aging_work_in_progress_chart.rb

@@ -113,7 +113,7 @@ class AgingWorkInProgressChart < ChartBase
 
   def ages_of_issues_that_crossed_column_boundary issues:, status_ids:
     issues.filter_map do |issue|
-      stop = issue.first_time_in_status(*status_ids)
+      stop = issue.first_time_in_status(*status_ids)&.to_time
       start, = issue.board.cycletime.started_stopped_times(issue)
 
       # Skip if either it hasn't crossed the boundary or we can't tell when it started.

data/lib/jirametrics/board.rb

@@ -4,7 +4,7 @@ class Board
   attr_reader :visible_columns, :raw, :possible_statuses, :sprints, :board_type
   attr_accessor :cycletime, :project_config
 
-  def initialize raw:, possible_statuses: StatusCollection.new
+  def initialize raw:, possible_statuses:
     @raw = raw
     @board_type = raw['type']
     @possible_statuses = possible_statuses

data/lib/jirametrics/change_item.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 class ChangeItem
-  attr_reader :field, :value_id, :old_value_id, :raw, :author
-  attr_accessor :value, :old_value, :time
+  attr_reader :field, :value_id, :old_value_id, :raw, :author, :time
+  attr_accessor :value, :old_value
 
   def initialize raw:, time:, author:, artificial: false
     @raw = 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']
+    @field = @raw['field']
+    @value = @raw['toString']
     @value_id = @raw['to'].to_i
     @old_value = @raw['fromString']
     @old_value_id = @raw['from']&.to_i
@@ -34,6 +35,11 @@ class ChangeItem
 
   def link? = (field == 'Link')
 
+  def labels? = (field == 'labels')
+
+  # 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}"

data/lib/jirametrics/chart_base.rb

@@ -169,13 +169,13 @@ 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
 
@@ -200,8 +200,8 @@ class ChartBase
         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.name : status.name
+    "<span title='Category: #{status.category.name}'>#{color_block color.name} #{text}</span>#{visibility}"
   end
 
   def icon_span title:, icon:
@@ -209,11 +209,11 @@ class ChartBase
   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
 

data/lib/jirametrics/cycletime_config.rb

@@ -44,18 +44,44 @@ class CycleTimeConfig
     started_stopped_times(issue).last
   end
 
-  def started_stopped_times issue
+  def fabricate_change_item time
+    deprecated date: '2024-12-16', message: 'This method should now return a ChangeItem not a Time', depth: 4
+    raw = {
+      'field' => 'Fabricated change',
+      'to' => '0',
+      'toString' => '',
+      'from' => '0',
+      'fromString' => ''
+    }
+    ChangeItem.new raw: raw, time: time, author: 'unknown', artificial: true
+  end
+
+  def started_stopped_changes issue
     started = @start_at.call(issue)
     stopped = @stop_at.call(issue)
 
+    # Obscure edge case where some of the start_at and stop_at blocks might return false in place of nil.
+    # If they are false then explicitly make them nil.
+    started ||= nil
+    stopped ||= nil
+
+    # These are only here for backwards compatibility. Hopefully nobody will ever need them.
+    started = fabricate_change_item(started) if !started.nil? && !started.is_a?(ChangeItem)
+    stopped = fabricate_change_item(stopped) if !stopped.nil? && !stopped.is_a?(ChangeItem)
+
     # In the case where started and stopped are exactly the same time, we pretend that
     # it just stopped and never started. This allows us to have logic like 'in or right of'
     # for the start and not have it conflict.
-    started = nil if started == stopped
+    started = nil if started&.time == stopped&.time
 
     [started, stopped]
   end
 
+  def started_stopped_times issue
+    started, stopped = started_stopped_changes(issue)
+    [started&.time, stopped&.time]
+  end
+
   def started_stopped_dates issue
     started_time, stopped_time = started_stopped_times(issue)
     [started_time&.to_date, stopped_time&.to_date]

data/lib/jirametrics/cycletime_histogram.rb

@@ -41,6 +41,8 @@ class CycletimeHistogram < ChartBase
       )
     end
 
+    return "<h1>#{@header_text}</h1>No data matched the selected criteria. Nothing to show." if data_sets.empty?
+
     wrap_and_render(binding, __FILE__)
   end
 

data/lib/jirametrics/data_quality_report.rb

@@ -112,8 +112,8 @@ class DataQualityReport < ChartBase
     @entries.reject { |entry| entry.problems.empty? }
   end
 
-  def category_name_for status_name:, board:
-    board.possible_statuses.find { |status| status.name == status_name }&.category_name
+  def category_name_for status_id:, board:
+    board.possible_statuses.find_by_id(status_id)&.category&.name
   end
 
   def initialize_entries
@@ -184,7 +184,7 @@ class DataQualityReport < ChartBase
       index = entry.issue.board.visible_columns.find_index { |column| column.status_ids.include? change.value_id }
       if index.nil?
         # If it's a backlog status then ignore it. Not supposed to be visible.
-        next if entry.issue.board.backlog_statuses.include? change.value_id
+        next if entry.issue.board.backlog_statuses.include?(board.possible_statuses.find_by_id(change.value_id))
 
         detail = "Status #{format_status change.value, board: board} is not on the board"
         if issue.board.possible_statuses.expand_statuses(change.value).empty?
@@ -198,8 +198,8 @@ class DataQualityReport < ChartBase
       elsif change.old_value.nil?
         # Do nothing
       elsif index < last_index
-        new_category = category_name_for(status_name: change.value, board: board)
-        old_category = category_name_for(status_name: change.old_value, board: board)
+        new_category = category_name_for(status_id: change.value_id, board: board)
+        old_category = category_name_for(status_id: change.old_value_id, board: board)
 
         if new_category == old_category
           entry.report(
@@ -365,8 +365,8 @@ class DataQualityReport < ChartBase
     if percentage_work_included < 85
       html << <<-HTML
         Consider whether looking at only #{percentage_work_included}% of the total data points is enough
-        to come to any reasonable conclusions. See <a href="https://en.wikipedia.org/wiki/Survivorship_bias">
-        Survivorship Bias</a>.
+        to come to any reasonable conclusions. See <a href="https://unconsciousagile.com/2024/11/19/survivor-bias.html">
+        Survivor Bias</a>.
       HTML
     end
     html

data/lib/jirametrics/download_config.rb

@@ -20,8 +20,8 @@ class DownloadConfig
     @rolling_date_count
   end
 
-  def no_earlier_than date = nil
-    @no_earlier_than = Date.parse(date) unless date.nil?
+  def no_earlier_than date = :not_set
+    @no_earlier_than = Date.parse(date) unless date == :not_set
     @no_earlier_than
   end
 

data/lib/jirametrics/downloader.rb

@@ -39,6 +39,7 @@ class Downloader
     # board_ids = @download_config.board_ids
 
     remove_old_files
+    update_status_history_file
     download_statuses
     find_board_ids.each do |id|
       board = download_board_configuration board_id: id
@@ -66,7 +67,7 @@ class Downloader
 
   def download_issues board:
     log "  Downloading primary issues for board #{board.id}", both: true
-    path = "#{@target_path}#{@download_config.project_config.file_prefix}_issues/"
+    path = File.join(@target_path, "#{file_prefix}_issues/")
     unless Dir.exist?(path)
       log "  Creating path #{path}"
       Dir.mkdir(path)
@@ -153,30 +154,58 @@ class Downloader
 
     @file_system.save_json(
       json: json,
-      filename: "#{@target_path}#{@download_config.project_config.file_prefix}_statuses.json"
+      filename: File.join(@target_path, "#{file_prefix}_statuses.json")
     )
   end
 
+  def update_status_history_file
+    status_filename = File.join(@target_path, "#{file_prefix}_statuses.json")
+    return unless file_system.file_exist? status_filename
+
+    status_json = file_system.load_json(status_filename)
+
+    history_filename = File.join(@target_path, "#{file_prefix}_status_history.json")
+    history_json = file_system.load_json(history_filename) if file_system.file_exist? history_filename
+
+    if history_json
+      file_system.log '  Updating status history file', also_write_to_stderr: true
+    else
+      file_system.log '  Creating status history file', also_write_to_stderr: true
+      history_json = []
+    end
+
+    status_json.each do |status_item|
+      id = status_item['id']
+      history_item = history_json.find { |s| s['id'] == id }
+      history_json.delete(history_item) if history_item
+      history_json << status_item
+    end
+
+    file_system.save_json(filename: history_filename, json: history_json)
+  end
+
   def download_board_configuration board_id:
     log "  Downloading board configuration for board #{board_id}", both: true
     json = @jira_gateway.call_url relative_url: "/rest/agile/1.0/board/#{board_id}/configuration"
 
     exit_if_call_failed json
 
-    file_prefix = @download_config.project_config.file_prefix
-    @file_system.save_json json: json, filename: "#{@target_path}#{file_prefix}_board_#{board_id}_configuration.json"
+    @file_system.save_json(
+      json: json,
+      filename: File.join(@target_path, "#{file_prefix}_board_#{board_id}_configuration.json")
+    )
 
     # We have a reported bug that blew up on this line. Moved it after the save so we can
     # actually look at the returned json.
     @board_id_to_filter_id[board_id] = json['filter']['id'].to_i
 
     download_sprints board_id: board_id if json['type'] == 'scrum'
-    Board.new raw: json
+    # TODO: Should be passing actual statuses, not empty list
+    Board.new raw: json, possible_statuses: StatusCollection.new
   end
 
   def download_sprints board_id:
     log "  Downloading sprints for board #{board_id}", both: true
-    file_prefix = @download_config.project_config.file_prefix
     max_results = 100
     start_at = 0
     is_last = false
@@ -188,7 +217,7 @@ class Downloader
 
       @file_system.save_json(
         json: json,
-        filename: "#{@target_path}#{file_prefix}_board_#{board_id}_sprints_#{start_at}.json"
+        filename: File.join(@target_path, "#{file_prefix}_board_#{board_id}_sprints_#{start_at}.json")
       )
       is_last = json['isLast']
       max_results = json['maxResults']
@@ -201,7 +230,7 @@ class Downloader
   end
 
   def metadata_pathname
-    "#{@target_path}#{@download_config.project_config.file_prefix}_meta.json"
+    File.join(@target_path, "#{file_prefix}_meta.json")
   end
 
   def load_metadata
@@ -244,17 +273,17 @@ class Downloader
   end
 
   def remove_old_files
-    file_prefix = @download_config.project_config.file_prefix
     Dir.foreach @target_path do |file|
       next unless file.match?(/^#{file_prefix}_\d+\.json$/)
+      next if file == "#{file_prefix}_status_history.json"
 
-      File.unlink "#{@target_path}#{file}"
+      File.unlink File.join(@target_path, file)
     end
 
     return if @cached_data_format_is_current
 
     # Also throw away all the previously downloaded issues.
-    path = File.join @target_path, "#{file_prefix}_issues"
+    path = File.join(@target_path, "#{file_prefix}_issues")
     return unless File.exist? path
 
     Dir.foreach path do |file|
@@ -292,4 +321,8 @@ class Downloader
 
     segments.join ' AND '
   end
+
+  def file_prefix
+    @download_config.project_config.get_file_prefix
+  end
 end

data/lib/jirametrics/examples/aggregated_project.rb

@@ -11,6 +11,7 @@ class Exporter
   def aggregated_project name:, project_names:, settings: {}
     project name: name do
       puts name
+      file_prefix name
       self.settings.merge! settings
 
       aggregate do
@@ -19,8 +20,6 @@ class Exporter
         end
       end
 
-      file_prefix name
-
       file do
         file_suffix '.html'
         issues.reject! do |issue|
@@ -32,7 +31,7 @@ class Exporter
           board_lines = []
           included_projects.each do |project|
             project.all_boards.each_value do |board|
-              board_lines << "<a href='#{project.file_prefix}.html'>#{board.name}</a> from project #{project.name}"
+              board_lines << "<a href='#{project.get_file_prefix}.html'>#{board.name}</a> from project #{project.name}"
             end
           end
           board_lines.sort.each { |line| html "<li>#{line}</li>", type: :header }

data/lib/jirametrics/examples/standard_project.rb

@@ -10,15 +10,15 @@ class Exporter
 
     project name: name do
       puts name
-      self.anonymize if anonymize
+      file_prefix file_prefix
 
+      self.anonymize if anonymize
       self.settings.merge! settings
 
       status_category_mappings.each do |status, category|
         status_category_mapping status: status, category: category
       end
 
-      file_prefix file_prefix
       download do
         self.rolling_date_count(rolling_date_count) if rolling_date_count
         self.no_earlier_than(no_earlier_than) if no_earlier_than

data/lib/jirametrics/expedited_chart.rb

@@ -63,7 +63,7 @@ class ExpeditedChart < ChartBase
       next unless change.priority?
 
       if expedited_priority_names.include? change.value
-        expedite_start = change.time
+        expedite_start = change.time.to_date
       elsif expedite_start
         start_date = expedite_start.to_date
         stop_date = change.time.to_date
@@ -72,7 +72,7 @@ class ExpeditedChart < ChartBase
            (start_date < date_range.begin && stop_date > date_range.end)
 
           result << [expedite_start, :expedite_start]
-          result << [change.time, :expedite_stop]
+          result << [change.time.to_date, :expedite_stop]
         end
         expedite_start = nil
       end
@@ -109,11 +109,11 @@ class ExpeditedChart < ChartBase
 
   def make_expedite_lines_data_set issue:, expedite_data:
     cycletime = issue.board.cycletime
-    started_time, stopped_time = cycletime.started_stopped_times(issue)
+    started_date, stopped_date = cycletime.started_stopped_dates(issue)
 
-    expedite_data << [started_time, :issue_started] if started_time
-    expedite_data << [stopped_time, :issue_stopped] if stopped_time
-    expedite_data.sort_by! { |a| a[0] }
+    expedite_data << [started_date, :issue_started] if started_date
+    expedite_data << [stopped_date, :issue_stopped] if stopped_date
+    expedite_data.sort_by!(&:first)
 
     # If none of the data would be visible on the chart then skip it.
     return nil unless expedite_data.any? { |time, _action| time.to_date >= date_range.begin }
@@ -150,7 +150,7 @@ class ExpeditedChart < ChartBase
 
     unless expedite_data.empty?
       last_change_time = expedite_data[-1][0].to_date
-      if last_change_time && last_change_time <= date_range.end && stopped_time.nil?
+      if last_change_time && last_change_time <= date_range.end && stopped_date.nil?
         data << make_point(issue: issue, time: date_range.end, label: 'Still ongoing', expedited: expedited)
         dot_colors << '' # It won't be visible so it doesn't matter
         point_styles << 'dash'

data/lib/jirametrics/exporter.rb

@@ -3,11 +3,11 @@
 require 'fileutils'
 
 class Object
-  def deprecated message:, date:
+  def deprecated message:, date:, depth: 2
     text = +''
     text << "Deprecated(#{date}): "
     text << message
-    caller(1..2).each do |line|
+    caller(1..depth).each do |line|
       text << "\n-> Called from #{line}"
     end
     warn text

data/lib/jirametrics/file_config.rb

@@ -56,7 +56,7 @@ class FileConfig
   def output_filename
     segments = []
     segments << project_config.target_path
-    segments << project_config.file_prefix
+    segments << project_config.get_file_prefix
     segments << (@file_suffix || "-#{@today}.csv")
     segments.join
   end
@@ -103,7 +103,7 @@ class FileConfig
   def to_datetime object
     return nil if object.nil?
 
-    object = object.to_datetime
+    object = object.to_time.to_datetime
     object = object.new_offset(@timezone_offset) if @timezone_offset
     object
   end

data/lib/jirametrics/file_system.rb

@@ -31,6 +31,10 @@ class FileSystem
     File.write(filename, content)
   end
 
+  def warning message
+    log "Warning: #{message}", also_write_to_stderr: true
+  end
+
   def log message, also_write_to_stderr: false
     logfile.puts message
     $stderr.puts message if also_write_to_stderr # rubocop:disable Style/StderrPuts
@@ -51,4 +55,8 @@ class FileSystem
   def foreach root, &block
     Dir.foreach root, &block
   end
+
+  def file_exist? filename
+    File.exist? filename
+  end
 end

data/lib/jirametrics/html/index.css

@@ -19,6 +19,7 @@
   --status-category-todo-color: gray;
   --status-category-inprogress-color: #2663ff;
   --status-category-done-color: #00ff00;
+  --status-category-unknown-color: black;
 
   --aging-work-bar-chart-percentage-line-color: red;
   --aging-work-bar-chart-separator-color: white;
@@ -126,6 +127,12 @@ ul.quality_report {
   }
 }
 
+#footer {
+  text-align: center;
+  margin-top: 1em;
+  border-top: 1px solid gray;
+}
+
 @media screen and (prefers-color-scheme: dark) {
   :root {
     --non-working-days-color: #2f2f2f;

data/lib/jirametrics/html/index.erb

@@ -30,9 +30,6 @@
     </style>
   </head>
   <body>
-    <div>
-      Page generated <%= (timezone_offset.nil? ? DateTime.now : DateTime.now.new_offset(timezone_offset)).strftime('%Y-%b-%d at %I:%M:%S%P') %>
-    </div>
     <%= "\n" + @sections.collect { |text, type| text if type == :header }.compact.join("\n\n") %>
     <%= "\n" + @sections.collect { |text, type| text if type == :body }.compact.join("\n\n") %>
   </body>

data/lib/jirametrics/html_report_config.rb

@@ -67,6 +67,8 @@ class HtmlReportConfig
     execute_chart DataQualityReport.new(@original_issue_times || {})
     @sections.rotate!(-1)
 
+    html create_footer
+
     html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
     css = load_css html_directory: html_directory
     erb = ERB.new file_system.load(File.join(html_directory, 'index.erb'))
@@ -202,4 +204,16 @@ class HtmlReportConfig
   def boards
     @file_config.project_config.board_configs.collect(&:id).collect { |id| find_board id }
   end
+
+  def create_footer now: DateTime.now
+    now = now.new_offset(timezone_offset)
+    version = Gem.loaded_specs['jirametrics']&.version || 'Next'
+
+    <<~HTML
+      <section id="footer">
+        Report generated on <b>#{now.strftime('%Y-%b-%d')}</b> at <b>#{now.strftime('%I:%M:%S%P %Z')}</b>
+        with <a href="https://jirametrics.org">JiraMetrics</a> <b>v#{version}</b>
+      </section>
+    HTML
+  end
 end

data/lib/jirametrics/issue.rb

@@ -44,7 +44,7 @@ class Issue
 
   def summary = @raw['fields']['summary']
 
-  def status = Status.new(raw: @raw['fields']['status'])
+  def status = Status.from_raw(@raw['fields']['status'])
 
   def labels = @raw['fields']['labels'] || []
 
@@ -66,35 +66,45 @@ class Issue
   end
 
   def first_time_in_status *status_names
-    @changes.find { |change| change.current_status_matches(*status_names) }&.time
+    @changes.find { |change| change.current_status_matches(*status_names) }
   end
 
   def first_time_not_in_status *status_names
-    @changes.find { |change| change.status? && status_names.include?(change.value) == false }&.time
+    @changes.find { |change| change.status? && status_names.include?(change.value) == false }
   end
 
   def first_time_in_or_right_of_column column_name
     first_time_in_status(*board.status_ids_in_or_right_of_column(column_name))
   end
 
+  def first_time_label_added *labels
+    @changes.each do |change|
+      next unless change.labels?
+
+      change_labels = change.value.split
+      return change if change_labels.any? { |l| labels.include?(l) }
+    end
+    nil
+  end
+
   def still_in_or_right_of_column column_name
     still_in_status(*board.status_ids_in_or_right_of_column(column_name))
   end
 
   def still_in
-    time = nil
+    result = nil
     @changes.each do |change|
       next unless change.status?
 
       current_status_matched = yield change
 
-      if current_status_matched && time.nil?
-        time = change.time
-      elsif !current_status_matched && time
-        time = nil
+      if current_status_matched && result.nil?
+        result = change
+      elsif !current_status_matched && result
+        result = nil
       end
     end
-    time
+    result
   end
   private :still_in
 
@@ -108,8 +118,8 @@ class Issue
   # If it ever entered one of these categories and it's still there then what was the last time it entered
   def still_in_status_category *category_names
     still_in do |change|
-      status = find_status_by_name change.value
-      category_names.include?(status.category_name) || category_names.include?(status.category_id)
+      status = find_status_by_id change.value_id, name: change.value
+      category_names.include?(status.category.name) || category_names.include?(status.category.id)
     end
   end
 
@@ -117,48 +127,53 @@ class Issue
     changes.reverse.find { |change| change.status? }
   end
 
-  # Are we currently in this status? If yes, then return the time of the most recent status change.
+  # Are we currently in this status? If yes, then return the most recent status change.
   def currently_in_status *status_names
     change = most_recent_status_change
     return false if change.nil?
 
-    change.time if change.current_status_matches(*status_names)
+    change if change.current_status_matches(*status_names)
   end
 
-  # Are we currently in this status category? If yes, then return the time of the most recent status change.
+  # Are we currently in this status category? If yes, then return the most recent status change.
   def currently_in_status_category *category_names
     change = most_recent_status_change
     return false if change.nil?
 
-    status = find_status_by_name change.value
-    change.time if status && category_names.include?(status.category_name)
+    status = find_status_by_id change.value_id, name: change.value
+    change if status && category_names.include?(status.category.name)
   end
 
-  def find_status_by_name name
-    status = board.possible_statuses.find_by_name(name)
+  def find_status_by_id id, name: nil
+    status = board.possible_statuses.find_by_id(id)
     return status if status
 
-    @board.project_config.file_system.log(
-      "Warning: Status name #{name.inspect} for issue #{key} not found in" \
-      " #{board.possible_statuses.collect(&:name).inspect}" \
-      "\n  See https://jirametrics.org/faq/#q1\n",
-      also_write_to_stderr: true
-    )
-    status = Status.new(name: name, category_name: 'In Progress')
-    board.possible_statuses << status
+    status = board.possible_statuses.fabricate_status_for id: id, name: name
+
+    message = +'The history for issue '
+    message << key
+    message << ' references a status ('
+    message << name.inspect << ':' if name
+    message << id.to_s
+    message << ') that can\'t be found in ['
+    message << board.possible_statuses.collect(&:to_s).join(', ')
+    message << "]. We are guessing that this belongs to the #{status.category} status category "
+    message << 'and that may be wrong. See https://jirametrics.org/faq/#q1 for more details'
+    board.project_config.file_system.warning message
+
     status
   end
 
   def first_status_change_after_created
-    @changes.find { |change| change.status? && change.artificial? == false }&.time
+    @changes.find { |change| change.status? && change.artificial? == false }
   end
 
   def first_time_in_status_category *category_names
     @changes.each do |change|
       next unless change.status?
 
-      category = find_status_by_name(change.value).category_name
-      return change.time if category_names.include? category
+      category = find_status_by_id(change.value_id).category.name
+      return change if category_names.include? category
     end
     nil
   end
@@ -177,11 +192,11 @@ class Issue
   end
 
   def first_resolution
-    @changes.find { |change| change.resolution? }&.time
+    @changes.find { |change| change.resolution? }
   end
 
   def last_resolution
-    @changes.reverse.find { |change| change.resolution? }&.time
+    @changes.reverse.find { |change| change.resolution? }
   end
 
   def assigned_to
@@ -624,7 +639,7 @@ class Issue
       # This was probably loaded as a linked issue, which means we don't know what board it really
       # belonged to. The best we can do is look at the status category. This case should be rare but
       # it can happen.
-      status.category_name == 'Done'
+      status.category.name == 'Done'
     else
       board.cycletime.done? self
     end

data/lib/jirametrics/project_config.rb

@@ -32,7 +32,7 @@ class ProjectConfig
   end
 
   def data_downloaded?
-    File.exist? File.join(@target_path, "#{file_prefix}_meta.json")
+    File.exist? File.join(@target_path, "#{get_file_prefix}_meta.json")
   end
 
   def load_data
@@ -41,7 +41,6 @@ class ProjectConfig
     @has_loaded_data = true
     load_all_boards
     @id = guess_project_id
-    load_status_category_mappings
     load_project_metadata
     load_sprints
   end
@@ -116,82 +115,139 @@ class ProjectConfig
     @board_configs << config
   end
 
-  def file_prefix prefix = nil
-    @file_prefix = prefix unless prefix.nil?
+  def file_prefix prefix
+    # The file_prefix has to be set before almost everything else. It really should have been an attribute
+    # on the project declaration itself. Hindsight is 20/20.
+    if @file_prefix
+      raise "file_prefix should only be set once. Was #{@file_prefix.inspect} and now changed to #{prefix.inspect}."
+    end
+
+    @file_prefix = prefix
+
+    # Yes, this is a wierd place to be initializing this. Unfortunately, it has to happen after the file_prefix
+    # is set but before anything inside the project block is run. If only we had made file_prefix an attribute
+    # on project, we wouldn't have this ugliness. 🤷‍♂️
+    load_status_category_mappings
+
     @file_prefix
   end
 
-  def status_category_mapping status:, category:
-    add_possible_status Status.new(name: status, category_name: category)
+  def get_file_prefix # rubocop:disable Naming/AccessorMethodName
+    raise 'file_prefix has not been set yet. Move it to the top of the project declaration.' unless @file_prefix
+
+    @file_prefix
   end
 
-  def load_all_boards
-    Dir.foreach(@target_path) do |file|
-      next unless file =~ /^#{@file_prefix}_board_(\d+)_configuration\.json$/
+  def status_guesses
+    statuses = {}
+    issues.each do |issue|
+      issue.changes.each do |change|
+        next unless change.status?
 
-      board_id = $1.to_i
-      load_board board_id: board_id, filename: "#{@target_path}#{file}"
+        (statuses[change.value] ||= Set.new) << change.value_id
+        (statuses[change.old_value] ||= Set.new) << change.old_value_id if change.old_value
+      end
     end
-    raise "No boards found for #{@file_prefix.inspect} in #{@target_path.inspect}" if @all_boards.empty?
+    statuses
   end
 
-  def load_board board_id:, filename:
-    board = Board.new(
-      raw: file_system.load_json(filename), possible_statuses: @possible_statuses
+  def status_category_mapping status:, category:
+    # Status might just be a name like "Review" or it might be a name:id pair like "Review:4"
+    parse_status = ->(line) { line =~ /^(.+):(\d+)$/ ? [$1, $2.to_i] : [line, nil] }
+
+    status, status_id = parse_status.call status
+    category, category_id = parse_status.call category
+
+    if status_id.nil?
+      guesses = status_guesses[status]
+      if guesses.nil?
+        file_system.warning "For status_category_mapping status: #{status.inspect}, category: #{category.inspect}\n" \
+          "Cannot guess status id for #{status.inspect} as no statuses found anywhere in the issues " \
+          "histories with that name. Since we can't find it, you probably don't need this mapping anymore so we're " \
+          "going to ignore it. If you really want it, then you'll need to specify a status id."
+        return
+      end
+
+      if guesses.size > 1
+        raise "Cannot guess status id as there are multiple ids for the name #{status.inspect}. Perhaps it's one " \
+          "of #{guesses.to_a.sort.inspect}. If you need this mapping then you must specify the status_id."
+      end
+
+      status_id = guesses.first
+      # TODO: This should be a deprecation instead but we can't currently assert against those
+      file_system.log "status_category_mapping for #{status.inspect} has been mapped to id #{status_id}. " \
+        "If that's incorrect then specify the status_id."
+    end
+
+    found_category = possible_statuses.find_category_by_name category
+    found_category_id = found_category&.id # possible_statuses.find_category_id_by_name category
+    if category_id && category_id != found_category_id
+      raise "ID is incorrect for status category #{category.inspect}. Did you mean #{found_category_id}?"
+    end
+
+    add_possible_status(
+      Status.new(
+        name: status, id: status_id,
+        category_name: category, category_id: found_category_id, category_key: found_category.key
+      )
     )
-    board.project_config = self
-    @all_boards[board_id] = board
   end
 
-  def raise_with_message_about_missing_category_information all_issues = @issues
-    message = +''
-    message << "Could not determine categories for some of the statuses used in this data set.\n" \
-      "Use the 'status_category_mapping' declaration in your config to manually add one.\n" \
-      'The mappings we do know about are below:'
+  def add_possible_status status
+    existing_status = @possible_statuses.find_by_id status.id
 
-    @possible_statuses.each do |status|
-      message << "\n  status: #{status.name.inspect}, category: #{status.category_name.inspect}"
+    if existing_status && existing_status.name != status.name
+      raise "Attempting to redefine the name for status #{status.id} from " \
+        "#{existing_status.name.inspect} to #{status.name.inspect}"
     end
 
-    message << "\n\nThe ones we're missing are the following:"
+    # If it isn't there, add it and go.
+    return @possible_statuses << status unless existing_status
 
-    find_statuses_with_no_category_information(all_issues).each do |status_name|
-      message << "\n  status: #{status_name.inspect}, category: <unknown>"
+    unless status == existing_status
+      raise "Redefining status category for status #{status}. " \
+        "original: #{existing_status.category}, " \
+        "new: #{status.category}"
     end
 
-    raise message
+    # We're registering one we already knew about. This may happen if someone specified a status_category_mapping
+    # for something that was already returned from jira. This isn't  problem so just ignore it.
+    existing_status
   end
 
-  def find_statuses_with_no_category_information all_issues
-    missing_statuses = []
-    all_issues.each do |issue|
-      issue.changes.each do |change|
-        next unless change.status?
+  def load_all_boards
+    Dir.foreach(@target_path) do |file|
+      next unless file =~ /^#{get_file_prefix}_board_(\d+)_configuration\.json$/
 
-        missing_statuses << change.value unless find_status(name: change.value)
-      end
+      board_id = $1.to_i
+      load_board board_id: board_id, filename: "#{@target_path}#{file}"
     end
-    missing_statuses.uniq
+    raise "No boards found for #{get_file_prefix.inspect} in #{@target_path.inspect}" if @all_boards.empty?
+  end
+
+  def load_board board_id:, filename:
+    board = Board.new(
+      raw: file_system.load_json(filename), possible_statuses: @possible_statuses
+    )
+    board.project_config = self
+    @all_boards[board_id] = board
   end
 
   def load_status_category_mappings
-    filename = "#{@target_path}/#{file_prefix}_statuses.json"
+    filename = File.join @target_path, "#{get_file_prefix}_statuses.json"
+
     # We may not always have this file. Load it if we can.
     return unless File.exist? filename
 
-    statuses = file_system.load_json(filename)
-      .map { |snippet| Status.new(raw: snippet) }
-    statuses
-      .find_all { |status| status.global? }
-      .each { |status| add_possible_status status }
-    statuses
-      .find_all { |status| status.project_scoped? }
+    file_system
+      .load_json(filename)
+      .map { |snippet| Status.from_raw(snippet) }
       .each { |status| add_possible_status status }
   end
 
   def load_sprints
     file_system.foreach(@target_path) do |file|
-      next unless file =~ /^#{file_prefix}_board_(\d+)_sprints_\d+.json$/
+      next unless file =~ /^#{get_file_prefix}_board_(\d+)_sprints_\d+.json$/
 
       file_path = File.join(@target_path, file)
       board = @all_boards[$1.to_i]
@@ -214,56 +270,26 @@ class ProjectConfig
     end
   end
 
-  def add_possible_status status
-    existing_status = find_status(name: status.name)
-
-    if status.project_scoped?
-      # If the project specific status doesn't change anything then we don't care whether it's
-      # our project or not.
-      return if existing_status && existing_status.category_name == status.category_name
-
-      raise_ambiguous_project_id if @id.nil?
-
-      # Not our project, ignore it.
-      return unless status.project_id == @id
-
-      # Replace the old one with this
-      @possible_statuses.delete(existing_status)
-      @possible_statuses << status
-      return
-    end
-
-    # If it isn't there, add it and go.
-    return @possible_statuses << status unless existing_status
-
-    # We're registering the same one twice. Shouldn't be possible with the new status API but it
-    # did happen with the project specific one.
-    return if status.category_name == existing_status.category_name
-
-    # If we got this far then someone has called status_category_mapping and is attempting to
-    # change the category.
-    raise "Redefining status category #{status} with #{existing_status}. Was one set in the config?"
-  end
-
-  def raise_ambiguous_project_id
-    raise 'Ambiguous project id: There is a project specific status that could affect out calculations. ' \
-      'We are unable to automatically detect the id of the project so you will have to set it manually ' \
-      'in the configuration like: "project id: 5"'
-  end
-
-  def find_status name:
-    @possible_statuses.find_by_name name
-  end
-
   def load_project_metadata
-    filename = File.join @target_path, "#{file_prefix}_meta.json"
+    filename = File.join @target_path, "#{get_file_prefix}_meta.json"
     json = file_system.load_json(filename)
 
     @data_version = json['version'] || 1
 
-    start = json['date_start'] || json['time_start'] # date_start is the current format. Time is the old.
-    stop  = json['date_end'] || json['time_end']
-    @time_range = to_time(start)..to_time(stop, end_of_day: true)
+    start = to_time(json['date_start'] || json['time_start']) # date_start is the current format. Time is the old.
+    stop  = to_time(json['date_end'] || json['time_end'], end_of_day: true)
+
+    # If no_earlier_than was set then make sure it's applied here.
+    if download_config
+      download_config.run
+      no_earlier = download_config.no_earlier_than
+      if no_earlier
+        no_earlier = to_time(no_earlier.to_s)
+        start = no_earlier if start < no_earlier
+      end
+    end
+
+    @time_range = start..stop
 
     @jira_url = json['jira_url']
   rescue Errno::ENOENT
@@ -328,7 +354,7 @@ class ProjectConfig
 
       timezone_offset = exporter.timezone_offset
 
-      issues_path = File.join @target_path, "#{file_prefix}_issues"
+      issues_path = File.join @target_path, "#{get_file_prefix}_issues"
       if File.exist?(issues_path) && File.directory?(issues_path)
         issues = load_issues_from_issues_directory path: issues_path, timezone_offset: timezone_offset
       else

data/lib/jirametrics/sprint_burndown.rb

@@ -172,7 +172,7 @@ class SprintBurndown < ChartBase
     change_item.raw['to'].split(/\s*,\s*/).any? { |id| id.to_i == sprint.id }
   end
 
-  def data_set_by_story_points sprint:, change_data_for_sprint:
+  def data_set_by_story_points sprint:, change_data_for_sprint: # rubocop:disable Metrics/CyclomaticComplexity
     summary_stats = SprintSummaryStats.new
     summary_stats.completed = 0.0
 

data/lib/jirametrics/status.rb

@@ -4,29 +4,57 @@ require 'jirametrics/value_equality'
 
 class Status
   include ValueEquality
-  attr_reader :id, :category_name, :category_id, :project_id
+  attr_reader :id, :project_id, :category
   attr_accessor :name
 
-  def initialize name: nil, id: nil, category_name: nil, category_id: nil, project_id: nil, raw: nil
-    @name = name
-    @id = id
-    @category_name = category_name
-    @category_id = category_id
-    @project_id = project_id
+  class Category
+    attr_reader :id, :name, :key
+
+    def initialize id:, name:, key:
+      @id = id
+      @name = name
+      @key = key
+    end
 
-    return unless raw
+    def to_s
+      "#{name.inspect}:#{id.inspect}"
+    end
 
-    @raw = raw
-    @name = raw['name']
-    @id = raw['id'].to_i
+    def new? = (@key == 'new')
+    def indeterminate? = (@key == 'indeterminate')
+    def done? = (@key == 'done')
+  end
 
+  def self.from_raw raw
     category_config = raw['statusCategory']
-    @category_name = category_config['name']
-    @category_id = category_config['id'].to_i
 
-    # If this is a NextGen project then this status may be project specific. When this field is
-    # nil then the status is global.
-    @project_id = raw['scope']&.[]('project')&.[]('id')
+    legal_keys = %w[new indeterminate done]
+    unless legal_keys.include? category_config['key']
+      puts "Category key #{category_config['key'].inspect} should be one of #{legal_keys.inspect}. Found:\n" \
+        "#{category_config}"
+    end
+
+    Status.new(
+      name: raw['name'],
+      id: raw['id'].to_i,
+      category_name: category_config['name'],
+      category_id: category_config['id'].to_i,
+      category_key: category_config['key'],
+      project_id: raw['scope']&.[]('project')&.[]('id'),
+      artificial: false
+    )
+  end
+
+  def initialize name:, id:, category_name:, category_id:, category_key:, project_id: nil, artificial: true
+    # These checks are needed because nils used to be possible and now they aren't.
+    raise 'id cannot be nil' if id.nil?
+    raise 'category_id cannot be nil' if category_id.nil?
+
+    @name = name
+    @id = id
+    @category = Category.new id: category_id, name: category_name, key: category_key
+    @project_id = project_id
+    @artificial = artificial
   end
 
   def project_scoped?
@@ -38,18 +66,26 @@ class Status
   end
 
   def to_s
-    result = "Status(name=#{@name.inspect}," \
-      " id=#{@id.inspect}," \
-      " category_name=#{@category_name.inspect}," \
-      " category_id=#{@category_id.inspect}," \
-      " project_id=#{@project_id}"
-    result << ' artificial' if artificial?
-    result << ')'
-    result
+    "#{name.inspect}:#{id.inspect}"
   end
 
   def artificial?
-    @raw.nil?
+    @artificial
+  end
+
+  def == other
+    @id == other.id && @name == other.name && @category.id == other.category.id && @category.name == other.category.name
+  end
+
+  def inspect
+    result = []
+    result << "Status(name: #{@name.inspect}"
+    result << "id: #{@id.inspect}"
+    result << "project_id: #{@project_id}" if @project_id
+    category = self.category
+    result << "category: {name:#{category.name.inspect}, id: #{category.id.inspect}, key: #{category.key.inspect}}"
+    result << 'artificial' if artificial?
+    result.join(', ') << ')'
   end
 
   def value_equality_ignored_variables

data/lib/jirametrics/status_collection.rb

@@ -13,7 +13,7 @@ class StatusCollection
     excluding = expand_statuses excluding
 
     @list.filter_map do |status|
-      keep = status.category_name == category_name ||
+      keep = status.category.name == category_name ||
         including.any? { |s| s.name == status.name }
       keep = false if excluding.any? { |s| s.name == status.name }
 
@@ -56,12 +56,45 @@ class StatusCollection
     filter_status_names category_name: 'Done', including: including, excluding: excluding
   end
 
-  def find_by_name name
-    find { |status| status.name == name }
+  # Return the status matching this id or nil if it can't be found.
+  def find_by_id id
+    @list.find { |status| status.id == id }
+  end
+
+  def find_all_by_name name
+    @list.select { |status| status.name == name }
+  end
+
+  def find_category_by_name name
+    category = @list.find { |status| status.category.name == name }&.category
+    unless category
+      set = Set.new
+      @list.each do |status|
+        set << status.category.to_s
+      end
+      raise "Unable to find status category #{name.inspect} in [#{set.to_a.sort.join(', ')}]"
+    end
+    category
+  end
+
+  # This is used to create a status that was found in the history but has since been deleted.
+  def fabricate_status_for id:, name:
+    first_in_progress_status = @list.find { |s| s.category.indeterminate? }
+    raise "Can't find even one in-progress status in [#{set.to_a.sort.join(', ')}]" unless first_in_progress_status
+
+    status = Status.new(
+      name: name,
+      id: id,
+      category_name: first_in_progress_status.category.name,
+      category_id: first_in_progress_status.category.id,
+      category_key: first_in_progress_status.category.key
+    )
+    self << status
+    status
   end
 
-  def find(&block)= @list.find(&block)
   def collect(&block) = @list.collect(&block)
+  def find(&block) = @list.find(&block)
   def each(&block) = @list.each(&block)
   def select(&block) = @list.select(&block)
   def <<(arg) = @list << arg
@@ -70,6 +103,6 @@ class StatusCollection
   def delete(object) = @list.delete(object)
 
   def inspect
-    "StatusCollection(#{@list.collect(&:inspect).join(', ')})"
+    "StatusCollection(#{@list.join(', ')})"
   end
 end

data/lib/jirametrics/throughput_chart.rb

@@ -82,7 +82,7 @@ class ThroughputChart < ChartBase
   def throughput_dataset periods:, completed_issues:
     periods.collect do |period|
       closed_issues = completed_issues.filter_map do |issue|
-        stop_date = issue.board.cycletime.started_stopped_times(issue).last&.to_date
+        stop_date = issue.board.cycletime.started_stopped_dates(issue).last
         [stop_date, issue] if stop_date && period.include?(stop_date)
       end
 

data/lib/jirametrics.rb

@@ -7,6 +7,13 @@ class JiraMetrics < Thor
     true
   end
 
+  map %w[--version -v] => :__print_version
+
+  desc '--version, -v', 'print the version'
+  def __print_version
+    puts Gem.loaded_specs['jirametrics'].version
+  end
+
   option :config
   option :name
   desc 'export', "Export data into either reports or CSV's as per the configuration"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: 2.7.3
+  version: '2.8'
 platform: ruby
 authors:
 - Mike Bowler
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-13 00:00:00.000000000 Z
+date: 2024-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: random-word