jirametrics 3.3.1 → 3.4

data/lib/jirametrics/testing.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Support for writing tests against jirametrics from outside this repo, for anyone building their
+# own charts or other extensions.
+#
+# Require this and you get the whole library loaded along with it, so a client test file needs
+# nothing else:
+#
+#   require 'jirametrics/testing'
+#
+# What is supported is exactly what this module holds: the Mock* classes below, plus the methods
+# to_time, to_date and empty_config_block. The require above loads the rest of the library too,
+# and that is a side effect of loading rather than a promise about any of it.
+#
+# The methods, and only the methods, arrive through include. Constants do not, because constant
+# lookup in an example block runs through the block's lexical scope rather than the ancestors of
+# the class it runs against:
+#
+#   RSpec.configure { |config| config.include JiraMetrics::Testing }
+#
+#   to_time '2024-01-01'                        # works, include supplies it
+#   JiraMetrics::Testing::MockIssue.empty(...)  # classes are named in full
+#
+# Add your own alias if the full name grates. That is your namespace to spend, so we don't spend
+# it for you:
+#
+#   MockIssue = JiraMetrics::Testing::MockIssue
+#
+# The require of 'jirametrics' below is not optional. This file nests inside the JiraMetrics class,
+# and reopening it before Thor has defined it raises a superclass mismatch.
+require 'jirametrics'
+require 'require_all'
+require_rel '.'
+
+class JiraMetrics
+  module Testing
+    # Accepts the date formats a test is likely to write, rather than only what Time.parse takes.
+    # A bare date means midnight, and a missing offset means UTC:
+    #
+    #   to_time '2024-01-01'                  => 2024-01-01 00:00:00 +0000
+    #   to_time '2024-01-01T12:34:56'         => 2024-01-01 12:34:56 +0000
+    #   to_time '2024-01-01T12:34:56.789'     => 2024-01-01 12:34:56.789 +0000
+    #   to_time '2024-01-01T12:34:56 +10:00'  => 2024-01-01 12:34:56 +1000
+    TIME_PATTERN = /
+      ^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})
+      (?<remainder>T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?<fraction>\.\d+)?
+      \s*(?<offset>[+-]\d{2}:?\d{2})?)?$
+    /x
+    private_constant :TIME_PATTERN
+
+    extend self
+
+    def to_time input
+      return input unless input.is_a? String
+
+      matches = input.match TIME_PATTERN
+      raise "Can't parse string: #{input.inspect}" unless matches
+
+      Time.parse format_matched_time(matches)
+    end
+
+    # The companion to to_time, for the many places a test wants a Date rather than a Time. Passes a
+    # Date straight through for the same reason to_time passes a Time through.
+    def to_date input
+      input.is_a?(Date) ? input : Date.parse(input)
+    end
+
+    # Every chart is constructed with a configuration block, so a test that only wants to exercise
+    # the chart itself still has to supply one. This is that block, doing nothing:
+    #
+    #   chart = MyCustomChart.new empty_config_block
+    #   chart.issues = [issue]
+    def empty_config_block = ->(_) {}
+
+    private
+
+    # Every optional part gets a default, which is what makes this long rather than interesting.
+    def format_matched_time matches
+      format(
+        '%<year>04d-%<month>02d-%<day>02dT-%<hour>02d:%<minute>02d:%<second>02d%<fraction>s%<offset>s',
+        year: matches[:year].to_i, month: matches[:month].to_i, day: matches[:day].to_i,
+        hour: (matches[:hour] || 0).to_i, minute: (matches[:minute] || 0).to_i,
+        second: (matches[:second] || 0).to_i,
+        fraction: matches[:fraction] || '', offset: matches[:offset] || '+0000'
+      )
+    end
+  end
+end

data/lib/jirametrics/time_based_histogram.rb

@@ -13,6 +13,7 @@ class TimeBasedHistogram < TimeBasedChart
   def initialize
     super
 
+    no_data_text '<%= render_header %><div>No data matched the selected criteria. Nothing to show.</div>'
     percentiles [50, 85, 98]
     @show_stats = true
   end
@@ -77,10 +78,7 @@ class TimeBasedHistogram < TimeBasedChart
       )
     end
 
-    if data_sets.empty?
-      return "<h1 class='foldable'>#{@header_text}</h1>" \
-             '<div>No data matched the selected criteria. Nothing to show.</div>'
-    end
+    return render_no_data if data_sets.empty?
 
     wrap_and_render(binding, __FILE__)
   end

data/lib/jirametrics/time_based_scatterplot.rb

@@ -22,6 +22,7 @@ class TimeBasedScatterplot < TimeBasedChart
   def initialize
     super
 
+    no_data_text '<%= render_header %><div>No data matched the selected criteria. Nothing to show.</div>'
     @percentage_lines = []
     @highest_y_value = 0
     @percentiles = [85]
@@ -56,10 +57,7 @@ class TimeBasedScatterplot < TimeBasedChart
       }
     end
 
-    if data_sets.empty?
-      return "<h1 class='foldable'>#{@header_text}</h1>" \
-        '<div>No data matched the selected criteria. Nothing to show.</div>'
-    end
+    return render_no_data if data_sets.empty?
 
     wrap_and_render(binding, __FILE__)
   end

data/lib/jirametrics/user.rb

@@ -1,12 +1,26 @@
 # frozen_string_literal: true
 
 class User
+  RENDERED_AVATAR_SIZE = '16x16'
+
+  # Jira omits the user entirely when there isn't one, so callers get nil rather than a User that
+  # raises on every question.
+  def self.from_raw raw
+    raw && new(raw: raw)
+  end
+
   def initialize raw:
     @raw = raw
   end
 
   def account_id = @raw['accountId']
-  def avatar_url = @raw['avatarUrls']['16x16']
   def active? = @raw['active']
-  def display_name = @raw['displayName']
+  def email_address = @raw['emailAddress']
+
+  # Nil when there's no name to show, in either spelling. Callers want different things in that
+  # case, so the default belongs at the call site. 'name' is what older Jira called displayName,
+  # and newer versions of Cloud don't return it.
+  def display_name = @raw['displayName'] || @raw['name']
+
+  def avatar_url = @raw['avatarUrls']&.[](RENDERED_AVATAR_SIZE)
 end

data/lib/jirametrics/wip_by_column_chart.rb

@@ -10,7 +10,7 @@ class WipByColumnChart < ChartBase
   # Long only because of the inline description_text heredoc and one-time setup; splitting wouldn't help.
   def initialize block # rubocop:disable Metrics/MethodLength
     super()
-    header_text 'WIP by column'
+    header_text 'WIP by column on board: <%= current_board.name %>'
     description_text <<-HTML
       <p>
         This chart shows how much time each board column has spent at different WIP (Work in Progress) levels.
@@ -58,7 +58,6 @@ class WipByColumnChart < ChartBase
   end
 
   def run
-    @header_text += " on board: #{current_board.name}"
     stats = column_stats
     @column_names = stats.collect(&:name)
     @wip_data = stats.collect do |stat|

data/lib/jirametrics.rb

@@ -157,7 +157,12 @@ class JiraMetrics < Thor
         exit 1
       end
 
-      require_rel 'jirametrics'
+      # The testing surface has no place in a production run, and the examples are opt-in: a config
+      # that wants standard_project requires it by name. Matching on the prefix also excludes
+      # testing.rb, which has to go with its directory because it require_rel's the whole tree.
+      not_autoloaded = %w[testing examples].collect { |name| File.join __dir__, 'jirametrics', name }
+      require_all(Dir[File.join(__dir__, 'jirametrics', '**', '*.rb')]
+        .reject { |file| not_autoloaded.any? { |prefix| file.start_with? prefix } })
       # Set only after the require above, so Exporter is defined. The config file we load below calls
       # Exporter.configure, which opens this log; the MCP server passes its own name so it doesn't
       # truncate jirametrics.log.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: '3.4'
 platform: ruby
 authors:
 - Mike Bowler
@@ -122,6 +122,7 @@ files:
 - lib/jirametrics/cfd_data_builder.rb
 - lib/jirametrics/change_item.rb
 - lib/jirametrics/chart_base.rb
+- lib/jirametrics/chart_format.rb
 - lib/jirametrics/color_palette.rb
 - lib/jirametrics/columns_config.rb
 - lib/jirametrics/css_variable.rb
@@ -201,6 +202,11 @@ files:
 - lib/jirametrics/status.rb
 - lib/jirametrics/status_collection.rb
 - lib/jirametrics/stitcher.rb
+- lib/jirametrics/testing.rb
+- lib/jirametrics/testing/mock_board.rb
+- lib/jirametrics/testing/mock_change_item.rb
+- lib/jirametrics/testing/mock_cycle_time_config.rb
+- lib/jirametrics/testing/mock_issue.rb
 - lib/jirametrics/throughput_by_completed_resolution_chart.rb
 - lib/jirametrics/throughput_chart.rb
 - lib/jirametrics/time_based_chart.rb