jirametrics 2.8 → 2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5bec8084c47e2383d25676b969891c6fc8e427d06427a1caf195378a830ff4f
-  data.tar.gz: e9364c2b43f66d90a651f50e115751c144f8dfc6f7d247b47dfd17495bdf167e
+  metadata.gz: 892b3686d9d53b05f9dd064524e99d38753b7c79685794a6bd6234d2d538e52d
+  data.tar.gz: c9412dfecec193196d523e1d811e89793269568eb31708192a075440d2806cb0
 SHA512:
-  metadata.gz: 82c740fa8d23565eb33edf1e244cde1b8b8ef2d88f753091fd0f3cfb7e20aa67c32fc22dca70d4076c25ad40898a0872c13f8af14173a26b33054faf8838df14
-  data.tar.gz: 66d5db7495165aa4ac0ea36acd27e1b77d2d4b4d4ebb7912fbbffee57c9c160b8cee3fc919884564370db51618438d24fc6fde5e47e2343560aca52b53917d4b
+  metadata.gz: a1ccae2dfc047912ced09176cac3af057b66350eb1436fe053457ff299629dafe801acb337c9ffa3702ec7c1ef0d3dd2dad84c8e6d2ff2842f6814d1ef6e43f2
+  data.tar.gz: e5b635a59c4026b51bd84d65cf3230cd90964f82cbb752e04534f1a4d7c59447e174f3d0bf480babe229b4fb91244f89f897d6da2c7c855ab189a4e943cd0a6d

data/lib/jirametrics/aging_work_bar_chart.rb

@@ -3,8 +3,6 @@
 require 'jirametrics/chart_base'
 
 class AgingWorkBarChart < ChartBase
-  @@next_id = 0
-
   def initialize block
     super()
 
@@ -116,7 +114,7 @@ class AgingWorkBarChart < ChartBase
     issue.changes.each do |change|
       next unless change.status?
 
-      status = issue.find_status_by_id change.value_id, name: change.value
+      status = issue.find_or_create_status id: change.value_id, name: change.value
 
       unless previous_start.nil? || previous_start < issue_started_time
         hash = {
@@ -162,8 +160,12 @@ class AgingWorkBarChart < ChartBase
   end
 
   def one_block_change_data_set starting_change:, ending_time:, issue_label:, stack:, issue_start_time:
-    deprecated message: 'blocked color should be set via css now', date: '2024-05-03' if settings['blocked_color']
-    deprecated message: 'blocked color should be set via css now', date: '2024-05-03' if settings['stalled_color']
+    if settings['blocked_color']
+      file_system.deprecated message: 'blocked color should be set via css now', date: '2024-05-03'
+    end
+    if settings['stalled_color']
+      file_system.deprecated message: 'stalled color should be set via css now', date: '2024-05-03'
+    end
 
     color = settings['blocked_color'] || '--blocked-color'
     color = settings['stalled_color'] || '--stalled-color' if starting_change.stalled?

data/lib/jirametrics/board.rb

@@ -27,9 +27,8 @@ class Board
   def backlog_statuses
     if @backlog_statuses.empty? && kanban?
       status_ids = status_ids_from_column raw['columnConfig']['columns'].first
-      @backlog_statuses = @possible_statuses.expand_statuses(status_ids) do |unknown_status|
-        # If a status is returned here that is no longer in the system then there's nothing useful
-        # we can do about it. Ignore it.
+      @backlog_statuses = status_ids.filter_map do |id|
+        @possible_statuses.find_by_id id
       end
     end
     @backlog_statuses

data/lib/jirametrics/board_config.rb

@@ -21,11 +21,15 @@ class BoardConfig
         'If so, remove it from there.'
     end
 
-    @board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
+    @board.cycletime = CycleTimeConfig.new(
+      parent_config: self, label: label, block: block, file_system: project_config.file_system
+    )
   end
 
   def expedited_priority_names *priority_names
-    deprecated date: '2024-09-15', message: 'Expedited priority names are now specified in settings'
+    project_config.exporter.file_system.deprecated(
+      date: '2024-09-15', message: 'Expedited priority names are now specified in settings'
+    )
     @project_config.settings['expedited_priority_names'] = priority_names
   end
 end

data/lib/jirametrics/chart_base.rb

@@ -27,9 +27,6 @@ class ChartBase
 
   def html_directory
     pathname = Pathname.new(File.realpath(__FILE__))
-    # basename = pathname.basename.to_s
-    # raise "Unexpected filename #{basename.inspect}" unless basename.match?(/^(.+)\.rb$/)
-
     "#{pathname.dirname}/html"
   end
 
@@ -179,18 +176,33 @@ class ChartBase
     @description_text
   end
 
+  # Convert a number like 1234567 into the string "1,234,567"
   def format_integer number
     number.to_s.reverse.scan(/.{1,3}/).join(',').reverse
   end
 
-  def format_status name_or_id, board:, is_category: false
-    begin
-      statuses = board.possible_statuses.expand_statuses([name_or_id])
-    rescue StatusNotFoundError
-      return "<span style='color: red'>#{name_or_id}</span>"
+  # object will be either a Status or a ChangeItem
+  # if it's a ChangeItem then use_old_status will specify whether we're using the new or old
+  # Either way, is_category will format the category rather than the status
+  def format_status object, board:, is_category: false, use_old_status: false
+    status = nil
+    error_message = nil
+
+    case object
+    when ChangeItem
+      id = use_old_status ? object.old_value_id : object.value_id
+      status = board.possible_statuses.find_by_id(id)
+      if status.nil?
+        error_message = use_old_status ? object.old_value : object.value
+      end
+    when Status
+      status = object
+    else
+      raise "Unexpected type: #{object.class}"
     end
 
-    status = statuses.first
+    return "<span style='color: red'>#{error_message}</span>" if error_message
+
     color = status_category_color status
 
     visibility = ''

data/lib/jirametrics/cycletime_config.rb

@@ -8,10 +8,14 @@ class CycleTimeConfig
 
   attr_reader :label, :parent_config
 
-  def initialize parent_config:, label:, block:, today: Date.today
+  def initialize parent_config:, label:, block:, file_system: nil, today: Date.today
     @parent_config = parent_config
     @label = label
     @today = today
+
+    # If we hit something deprecated and this is nil then we'll blow up. Although it's ugly, this
+    # may make it easier to find problems in the test code ;-)
+    @file_system = file_system
     instance_eval(&block) unless block.nil?
   end
 
@@ -35,17 +39,19 @@ class CycleTimeConfig
   end
 
   def started_time issue
-    deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
+    @file_system.deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
     started_stopped_times(issue).first
   end
 
   def stopped_time issue
-    deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
+    @file_system.deprecated date: '2024-10-16', message: 'Use started_stopped_times() instead'
     started_stopped_times(issue).last
   end
 
   def fabricate_change_item time
-    deprecated date: '2024-12-16', message: 'This method should now return a ChangeItem not a Time', depth: 4
+    @file_system.deprecated(
+      date: '2024-12-16', message: "This method should now return a ChangeItem not a #{time.class}", depth: 4
+    )
     raw = {
       'field' => 'Fabricated change',
       'to' => '0',

data/lib/jirametrics/data_quality_report.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class DataQualityReport < ChartBase
-  attr_reader :original_issue_times # For testing purposes only
+  attr_reader :discarded_changes_data, :entries # Both for testing purposes only
   attr_accessor :board_id
 
   class Entry
@@ -19,10 +19,10 @@ class DataQualityReport < ChartBase
     end
   end
 
-  def initialize original_issue_times
+  def initialize discarded_changes_data
     super()
 
-    @original_issue_times = original_issue_times
+    @discarded_changes_data = discarded_changes_data
 
     header_text 'Data Quality Report'
     description_text <<-HTML
@@ -50,6 +50,7 @@ class DataQualityReport < ChartBase
       scan_for_issues_not_started_with_subtasks_that_have entry: entry
       scan_for_incomplete_subtasks_when_issue_done entry: entry
       scan_for_discarded_data entry: entry
+      scan_for_items_blocked_on_closed_tickets entry: entry
     end
 
     scan_for_issues_on_multiple_boards entries: @entries
@@ -73,6 +74,7 @@ class DataQualityReport < ChartBase
     result << render_problem_type(:issue_not_started_but_subtasks_have)
     result << render_problem_type(:incomplete_subtasks_when_issue_done)
     result << render_problem_type(:issue_on_multiple_boards)
+    result << render_problem_type(:items_blocked_on_closed_tickets)
     result << '</ul>'
 
     result
@@ -102,9 +104,13 @@ class DataQualityReport < ChartBase
 
   # Return a format that's easier to assert against
   def testable_entries
-    format = '%Y-%m-%d %H:%M:%S %z'
+    formatter = ->(time) { time&.strftime('%Y-%m-%d %H:%M:%S %z') || '' }
     @entries.collect do |entry|
-      [entry.started&.strftime(format) || '', entry.stopped&.strftime(format) || '', entry.issue]
+      [
+        formatter.call(entry.started),
+        formatter.call(entry.stopped),
+        entry.issue
+      ]
     end
   end
 
@@ -112,10 +118,6 @@ class DataQualityReport < ChartBase
     @entries.reject { |entry| entry.problems.empty? }
   end
 
-  def category_name_for status_id:, board:
-    board.possible_statuses.find_by_id(status_id)&.category&.name
-  end
-
   def initialize_entries
     @entries = @issues.filter_map do |issue|
       started, stopped = issue.board.cycletime.started_stopped_times(issue)
@@ -139,10 +141,8 @@ class DataQualityReport < ChartBase
   def scan_for_completed_issues_without_a_start_time entry:
     return unless entry.stopped && entry.started.nil?
 
-    status_names = entry.issue.changes.filter_map do |change|
-      next unless change.status?
-
-      format_status change.value, board: entry.issue.board
+    status_names = entry.issue.status_changes.filter_map do |change|
+      format_status change, board: entry.issue.board
     end
 
     entry.report(
@@ -157,14 +157,14 @@ class DataQualityReport < ChartBase
     changes_after_done = entry.issue.changes.select do |change|
       change.status? && change.time >= entry.stopped
     end
-    done_status = changes_after_done.shift.value
+    done_status = changes_after_done.shift
 
     return if changes_after_done.empty?
 
     board = entry.issue.board
     problem = "Completed on #{entry.stopped.to_date} with status #{format_status done_status, board: board}."
     changes_after_done.each do |change|
-      problem << " Changed to #{format_status change.value, board: board} on #{change.time.to_date}."
+      problem << " Changed to #{format_status change, board: board} on #{change.time.to_date}."
     end
     entry.report(
       problem_key: :status_changes_after_done,
@@ -186,9 +186,9 @@ class DataQualityReport < ChartBase
         # If it's a backlog status then ignore it. Not supposed to be visible.
         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?
-          detail = "Status #{format_status change.value, board: board} cannot be found at all. Was it deleted?"
+        detail = "Status #{format_status change, board: board} is not on the board"
+        if issue.board.possible_statuses.find_by_id(change.value_id).nil?
+          detail = "Status #{format_status change, board: board} cannot be found at all. Was it deleted?"
         end
 
         # If it's been moved back to backlog then it's on a different report. Ignore it here.
@@ -198,24 +198,24 @@ class DataQualityReport < ChartBase
       elsif change.old_value.nil?
         # Do nothing
       elsif index < last_index
-        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)
+        new_category = board.possible_statuses.find_by_id(change.value_id).category.name
+        old_category = board.possible_statuses.find_by_id(change.old_value_id).category.name
 
         if new_category == old_category
           entry.report(
             problem_key: :backwords_through_statuses,
-            detail: "Moved from #{format_status change.old_value, board: board}" \
-              " to #{format_status change.value, board: board}" \
+            detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
+              " to #{format_status change, board: board}" \
               " on #{change.time.to_date}"
           )
         else
           entry.report(
             problem_key: :backwards_through_status_categories,
-            detail: "Moved from #{format_status change.old_value, board: board}" \
-              " to #{format_status change.value, board: board}" \
-              " on #{change.time.to_date}, " \
-              " crossing from category #{format_status old_category, board: board, is_category: true}" \
-              " to #{format_status new_category, board: board, is_category: true}."
+            detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
+              " to #{format_status change, board: board}" \
+              " on #{change.time.to_date}," \
+              " crossing from category #{format_status change, use_old_status: true, board: board, is_category: true}" \
+              " to #{format_status change, board: board, is_category: true}."
           )
         end
       end
@@ -224,16 +224,14 @@ class DataQualityReport < ChartBase
   end
 
   def scan_for_issues_not_created_in_a_backlog_status entry:, backlog_statuses:
-    return if backlog_statuses.empty?
-
     creation_change = entry.issue.changes.find { |issue| issue.status? }
 
     return if backlog_statuses.any? { |status| status.id == creation_change.value_id }
 
-    status_string = backlog_statuses.collect { |s| format_status s.name, board: entry.issue.board }.join(', ')
+    status_string = backlog_statuses.collect { |s| format_status s, board: entry.issue.board }.join(', ')
     entry.report(
       problem_key: :created_in_wrong_status,
-      detail: "Created in #{format_status creation_change.value, board: entry.issue.board}, " \
+      detail: "Created in #{format_status creation_change, board: entry.issue.board}, " \
         "which is not one of the backlog statuses for this board: #{status_string}"
     )
   end
@@ -266,6 +264,20 @@ class DataQualityReport < ChartBase
     )
   end
 
+  def scan_for_items_blocked_on_closed_tickets entry:
+    entry.issue.issue_links.each do |link|
+      this_active = !entry.stopped
+      other_active = !link.other_issue.board.cycletime.started_stopped_times(link.other_issue).last
+      next unless this_active && !other_active
+
+      entry.report(
+        problem_key: :items_blocked_on_closed_tickets,
+        detail: "#{entry.issue.key} thinks it's blocked on #{link.other_issue.key}, " \
+          "except #{link.other_issue.key} is closed."
+      )
+    end
+  end
+
   def subtask_label subtask
     "<img src='#{subtask.type_icon_url}' /> #{link_to_issue(subtask)} #{subtask.summary[..50].inspect}"
   end
@@ -314,10 +326,10 @@ class DataQualityReport < ChartBase
   end
 
   def scan_for_discarded_data entry:
-    hash = @original_issue_times[entry.issue]
+    hash = @discarded_changes_data&.find { |a| a[:issue] == entry.issue }
     return if hash.nil?
 
-    old_start_time = hash[:started_time]
+    old_start_time = hash[:original_start_time]
     cutoff_time = hash[:cutoff_time]
 
     old_start_date = old_start_time.to_date
@@ -352,7 +364,7 @@ class DataQualityReport < ChartBase
     <<-HTML
       #{label_issues problems.size} have had information discarded. This configuration is set
       to "reset the clock" if an item is moved back to the backlog after it's been started. This hides important
-      information and makes the data less accurate. <b>Moving items back to the backlog is strongly discouraged.</b>      HTML
+      information and makes the data less accurate. <b>Moving items back to the backlog is strongly discouraged.</b>
     HTML
   end
 
@@ -437,4 +449,11 @@ class DataQualityReport < ChartBase
       could result in more data points showing up on a chart then there really should be.
     HTML
   end
+
+  def render_items_blocked_on_closed_tickets problems
+    <<-HTML
+      For #{label_issues problems.size}, the issue is identified as being blocked by another issue. Yet,
+      that other issue is already completed so, by definition, it can't still be blocking.
+    HTML
+  end
 end

data/lib/jirametrics/examples/standard_project.rb

@@ -28,8 +28,8 @@ class Exporter
         block = boards[board_id]
         if block == :default
           block = lambda do |_|
-            start_at first_time_in_status_category('In Progress')
-            stop_at still_in_status_category('Done')
+            start_at first_time_in_status_category(:indeterminate)
+            stop_at still_in_status_category(:done)
           end
         end
         board id: board_id do

data/lib/jirametrics/exporter.rb

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

data/lib/jirametrics/file_config.rb

@@ -85,6 +85,11 @@ class FileConfig
 
   def html_report &block
     assert_only_one_filetype_config_set
+    if block.nil?
+      project_config.file_system.warning 'No charts were specified for the report. This is almost certainly a mistake.'
+      block = ->(_) {}
+    end
+
     @html_report = HtmlReportConfig.new file_config: self, block: block
   end
 
@@ -120,4 +125,11 @@ class FileConfig
     @file_suffix = suffix unless suffix.nil?
     @file_suffix
   end
+
+  def children
+    result = []
+    result << @columns if @columns
+    result << @html_report if @html_report
+    result
+  end
 end

data/lib/jirametrics/file_system.rb

@@ -31,13 +31,18 @@ class FileSystem
     File.write(filename, content)
   end
 
-  def warning message
-    log "Warning: #{message}", also_write_to_stderr: true
+  def warning message, more: nil
+    log "Warning: #{message}", more: more, also_write_to_stderr: true
   end
 
-  def log message, also_write_to_stderr: false
+  def log message, more: nil, also_write_to_stderr: false
+    message += " See #{logfile_name} for more details about this message." if more
+
     logfile.puts message
-    $stderr.puts message if also_write_to_stderr # rubocop:disable Style/StderrPuts
+    logfile.puts more if more
+    return unless also_write_to_stderr
+
+    $stderr.puts message # rubocop:disable Style/StderrPuts
   end
 
   # In some Jira instances, a sizeable portion of the JSON is made up of empty fields. I've seen
@@ -59,4 +64,14 @@ class FileSystem
   def file_exist? filename
     File.exist? filename
   end
+
+  def deprecated message:, date:, depth: 2
+    text = +''
+    text << "Deprecated(#{date}): "
+    text << message
+    caller(1..depth).each do |line|
+      text << "\n-> Called from #{line}"
+    end
+    log text, also_write_to_stderr: true
+  end
 end

data/lib/jirametrics/groupable_issue_chart.rb

@@ -6,9 +6,7 @@ require 'jirametrics/grouping_rules'
 module GroupableIssueChart
   def init_configuration_block user_provided_block, &default_block
     instance_eval(&user_provided_block)
-    return if @group_by_block
-
-    instance_eval(&default_block)
+    instance_eval(&default_block) unless @group_by_block
   end
 
   def grouping_rules &block

data/lib/jirametrics/html/aging_work_table.erb

@@ -40,7 +40,7 @@
             </div>
           <% end %>
         </td>
-        <td><%= format_status issue.status.name, board: issue.board %></td>
+        <td><%= format_status issue.status, board: issue.board %></td>
         <td><%= fix_versions_text(issue) %></td>
         <% if any_scrum_boards %>
           <td><%= sprints_text(issue) %></td>

data/lib/jirametrics/html/hierarchy_table.erb

@@ -22,7 +22,7 @@
           </span>
         </td>
         <td><span style="color: <%= color %>; font-style: italic;"><%= issue.summary[0..80] %></span></td>
-        <td><%= format_status issue.status.name, board: issue.board %></td>
+        <td><%= format_status issue.status, board: issue.board %></td>
       </tr>
     <% end %>
   </tbody>

data/lib/jirametrics/html_report_config.rb

@@ -5,16 +5,15 @@ require 'jirametrics/self_or_issue_dispatcher'
 
 class HtmlReportConfig
   include SelfOrIssueDispatcher
-  include DiscardChangesBefore
 
-  attr_reader :file_config, :sections
+  attr_reader :file_config, :sections, :charts
 
   def self.define_chart name:, classname:, deprecated_warning: nil, deprecated_date: nil
     lines = []
     lines << "def #{name} &block"
     lines << '  block = ->(_) {} unless block'
     if deprecated_warning
-      lines << "  deprecated date: #{deprecated_date.inspect}, message: #{deprecated_warning.inspect}"
+      lines << "  file_system.deprecated date: #{deprecated_date.inspect}, message: #{deprecated_warning.inspect}"
     end
     lines << "  execute_chart #{classname}.new(block)"
     lines << 'end'
@@ -43,14 +42,15 @@ class HtmlReportConfig
   def initialize file_config:, block:
     @file_config = file_config
     @block = block
-    @sections = []
+    @sections = [] # Where we store the chunks of text that will be assembled into the HTML
+    @charts = [] # Where we store all the charts we executed so we can assert against them.
   end
 
   def cycletime label = nil, &block
     @file_config.project_config.all_boards.each_value do |board|
       raise 'Multiple cycletimes not supported' if board.cycletime
 
-      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
+      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block, file_system: file_system)
     end
   end
 
@@ -64,7 +64,7 @@ class HtmlReportConfig
 
     # The quality report has to be generated last because otherwise cycletime won't have been
     # set. Then we have to rotate it to the first position so it's at the top of the report.
-    execute_chart DataQualityReport.new(@original_issue_times || {})
+    execute_chart DataQualityReport.new(file_config.project_config.discarded_changes_data)
     @sections.rotate!(-1)
 
     html create_footer
@@ -101,9 +101,8 @@ class HtmlReportConfig
     base_css
   end
 
-  def board_id id = nil
-    @board_id = id unless id.nil?
-    @board_id
+  def board_id id
+    @board_id = id
   end
 
   def timezone_offset
@@ -143,19 +142,6 @@ class HtmlReportConfig
     end
   end
 
-  def discard_changes_before_hook issues_cutoff_times
-    # raise 'Cycletime must be defined before using discard_changes_before' unless @cycletime
-
-    @original_issue_times = {}
-    issues_cutoff_times.each do |issue, cutoff_time|
-      started = issue.board.cycletime.started_stopped_times(issue).first
-      if started && started <= cutoff_time
-        # We only need to log this if data was discarded
-        @original_issue_times[issue] = { cutoff_time: cutoff_time, started_time: started }
-      end
-    end
-  end
-
   def dependency_chart &block
     execute_chart DependencyChart.new block
   end
@@ -175,7 +161,7 @@ class HtmlReportConfig
     chart.settings = settings
 
     chart.all_boards = project_config.all_boards
-    chart.board_id = find_board_id if chart.respond_to? :board_id=
+    chart.board_id = find_board_id
     chart.holiday_dates = project_config.exporter.holiday_dates
 
     time_range = @file_config.project_config.time_range
@@ -184,6 +170,7 @@ class HtmlReportConfig
 
     after_init_block&.call chart
 
+    @charts << chart
     html chart.run
   end
 
@@ -216,4 +203,12 @@ class HtmlReportConfig
       </section>
     HTML
   end
+
+  def discard_changes_before status_becomes: nil, &block
+    file_system.deprecated(
+      date: '2025-01-09',
+      message: 'discard_changes_before is now only supported at the project level'
+    )
+    file_config.project_config.discard_changes_before status_becomes: status_becomes, &block
+  end
 end