jirametrics 2.7.1 → 2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5bb71d8f3c6ab4cf1fa17ad93ad1c00ba1b8381c196bc15a054095a5a91917a
-  data.tar.gz: 790abb0404719d6b55d833ad76d34121875997f3ec3967f69f5d467fae203752
+  metadata.gz: f5bec8084c47e2383d25676b969891c6fc8e427d06427a1caf195378a830ff4f
+  data.tar.gz: e9364c2b43f66d90a651f50e115751c144f8dfc6f7d247b47dfd17495bdf167e
 SHA512:
-  metadata.gz: f71c2ae123a13435a1147ceaadf7f10364a6cdf1421b4f8491633936189e3744e58da4d99be6c43c6e8034d5f27afc470498532157ac15a7d4459a0399f6fc12
-  data.tar.gz: f33eb0ea450d6002b09d84311823fc20847327bb78dca5fa218c3f724a23f02d49f4ef0183e9dc02499e0eea1f5916147396538751192974926e1c197f4f0bb5
+  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

@@ -6,14 +6,18 @@ class FileSystem
   attr_accessor :logfile, :logfile_name
 
   # Effectively the same as File.read except it forces the encoding to UTF-8
-  def load filename
+  def load filename, supress_deprecation: false
+    if filename.end_with?('.json') && !supress_deprecation
+      deprecated(message: 'call load_json instead', date: '2024-11-13')
+    end
+
     File.read filename, encoding: 'UTF-8'
   end
 
   def load_json filename, fail_on_error: true
     return nil if fail_on_error == false && File.exist?(filename) == false
 
-    JSON.parse load(filename)
+    JSON.parse load(filename, supress_deprecation: true)
   end
 
   def save_json json:, filename:
@@ -27,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
@@ -43,4 +51,12 @@ class FileSystem
     end
     node
   end
+
+  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