jirametrics 3.3 → 3.4

data/lib/jirametrics/testing/mock_change_item.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+class JiraMetrics
+  module Testing
+    # Builds a ChangeItem for tests without going through Jira's changelog format.
+    #
+    # Normalises the arguments a caller is likely to get slightly wrong (a status given as a name when
+    # an id is wanted, a time given as a string) and, for status changes with an issue, validates the
+    # status against that issue's board so a typo surfaces loudly rather than silently passing.
+    class MockChangeItem
+      def initialize(
+        field:, value:, time:, value_id: nil, old_value: nil, old_value_id: nil,
+        artificial: false, issue: nil, field_id: nil
+      )
+        @field = field
+        @value = value
+        # Callers write dates as strings far more often than as Times.
+        @time = JiraMetrics::Testing.to_time time
+        @value_id = value_id
+        @old_value = old_value
+        @old_value_id = old_value_id
+        @artificial = artificial
+        @issue = issue
+        @field_id = field_id
+      end
+
+      def to_change_item
+        normalize_status_arguments
+        validate_status_change if @field == 'status' && @issue
+
+        ChangeItem.new time: @time, artificial: @artificial, author_raw: nil, raw: {
+          'field' => @field,
+          'to' => @value_id,
+          'toString' => @value,
+          'from' => @old_value_id,
+          'fromString' => @old_value,
+          'fieldId' => @field_id
+        }
+      end
+
+      # If either value or old_value is a Status object then pull the name and id off it.
+      private
+
+      def normalize_status_arguments
+        if @value.is_a? Status
+          @value_id = @value.id
+          @value = @value.name
+        end
+        return unless @old_value.is_a? Status
+
+        @old_value_id = @old_value.id
+        @old_value = @old_value.name
+      end
+
+      # Status names aren't unique, so a status name always has to be paired with an explicit id.
+      def validate_status_change
+        require_value_id!
+        require_old_value_id!
+        verify_value_id!
+        verify_old_value_id!
+      end
+
+      def require_value_id!
+        return unless @value && !@value_id
+
+        guesses = possible_statuses.find_all_by_name(@value).collect(&:id)
+        message = "ID was not specified for new status #{@value.inspect}. "
+        if guesses.empty?
+          message << "No statuses with name #{@value.inspect} but did find these: #{possible_statuses.inspect}"
+        else
+          message << "Perhaps you meant one of #{guesses.inspect}"
+        end
+        raise message
+      end
+
+      def require_old_value_id!
+        return unless @old_value && !@old_value_id
+
+        guesses = possible_statuses.find_all_by_name(@old_value).collect(&:id)
+        raise "ID was not specified for old status #{@old_value.inspect}. Perhaps you meant one of #{guesses.inspect}"
+      end
+
+      def verify_value_id!
+        return unless @value_id
+
+        status = possible_statuses.find_by_id(@value_id)
+        raise "No status found for id: #{@value_id} (#{@value.inspect}) in #{possible_statuses.inspect}" unless status
+        return if status.name == @value
+
+        raise "Value passed to mock_change (#{@value.inspect}:#{@value_id.inspect}) " \
+          "doesn't match the status found in the board (#{status})"
+      end
+
+      def verify_old_value_id!
+        return unless @old_value_id
+
+        status = possible_statuses.find_by_id(@old_value_id)
+        unless status
+          raise "No status found for id: #{@old_value_id} (#{@old_value.inspect}) in #{possible_statuses.inspect}"
+        end
+        return if status.name == @old_value
+
+        raise "Old value passed to mock_change (#{@old_value.inspect}:#{@old_value_id.inspect}) " \
+          "doesn't match the status found in the board (#{status})"
+      end
+
+      def possible_statuses
+        @issue.board.possible_statuses
+      end
+    end
+  end
+end

data/lib/jirametrics/testing/mock_cycle_time_config.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+class JiraMetrics
+  module Testing
+    # Stubs are matched by the issue's KEY, not by object identity, so every issue in a test needs its
+    # own key. Building two issues with the same key and stubbing both raises.
+    #
+    #   board.cycletime = MockCycleTimeConfig.new
+    #     .stub(issue1, started: '2021-01-02')
+    #     .stub(issue2, started: '2021-01-02', stopped: '2021-10-04')
+    #
+    # An issue with no stub at all reads as never started, which is a legitimate state and so cannot be
+    # distinguished from one you forgot.
+    class MockCycleTimeConfig < CycleTimeConfig
+      def initialize
+        super(possible_statuses: nil, label: nil, block: nil, settings: self.class.default_settings)
+        @stubs = []
+      end
+
+      # The same file ProjectConfig reads, resolved from this file's own location so that it works from
+      # wherever the caller happens to be rather than only from a checkout of this repo.
+      def self.default_settings
+        settings_file = File.expand_path '../settings.json', __dir__
+        JSON.parse(File.read(settings_file, encoding: 'UTF-8')).tap do |settings|
+          # A cached cycle time would outlive the stub that produced it, so a second stub for the same
+          # issue would appear to have no effect.
+          settings['cache_cycletime_calculations'] = false
+        end
+      end
+
+      # Returns self so that calls cascade.
+      def stub issue, started: nil, stopped: nil
+        key = issue.is_a?(Issue) ? issue.key : issue
+        assert_key_unused key
+        @stubs << [key, normalize_time(started), normalize_time(stopped)]
+        self
+      end
+
+      def started_stopped_changes(issue)
+        value = @stubs.find { |issue_key, _start, _stop| issue_key == issue.key }
+        return [nil, nil] unless value
+
+        [to_change(value[1]), to_change(value[2])]
+      end
+
+      private
+
+      def normalize_time value
+        value.is_a?(String) ? JiraMetrics::Testing.to_time(value) : value
+      end
+
+      # Only the first stub for a key is reachable, so a second one always means the test is asserting
+      # against something other than what it looks like.
+      def assert_key_unused key
+        return unless @stubs.any? { |existing, _start, _stop| existing == key }
+
+        raise "More than one stub for #{key}. Stubs are matched by issue key, so only the first would " \
+          'ever be used. Give each issue its own key.'
+      end
+
+      def to_change change
+        case change
+        when nil
+          nil
+        when ChangeItem
+          change
+        else
+          MockChangeItem.new(field: 'status', value: 'fake', value_id: 1_000_001, time: change&.to_time).to_change_item
+        end
+      end
+    end
+  end
+end

data/lib/jirametrics/testing/mock_issue.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class JiraMetrics
+  module Testing
+    # An Issue you can build without a fixture file and then add history to.
+    #
+    # MockIssue.new keeps Issue's own signature (raw:, board:) so that a MockIssue is substitutable for
+    # an Issue everywhere, including MockCycleTimeConfig's is_a?(Issue) check. The friendly constructor
+    # is MockIssue.empty, which builds the minimal raw hash for you.
+    class MockIssue < Issue
+      # Generated keys start well clear of the hand-written SP-1 and SP-2 that fixtures use.
+      FIRST_GENERATED_KEY_NUMBER = 1000
+
+      # A leap day on purpose. Anything that does its own date arithmetic, assumes 365-day years, or
+      # round-trips through a format that cannot represent Feb 29 will trip over this default rather
+      # than sailing past on a date that hides the bug.
+      DEFAULT_CREATED = '2024-02-29'
+
+      # The change is built and appended in one step, and returned for tests that need to hold on to it.
+      def add_change field:, value:, time:, value_id: nil, old_value: nil, old_value_id: nil,
+        artificial: false, field_id: nil
+        change = MockChangeItem.new(
+          issue: self, field: field, time: time, value: value, value_id: value_id,
+          old_value: old_value, old_value_id: old_value_id, artificial: artificial, field_id: field_id
+        ).to_change_item
+        changes << change
+        change
+      end
+
+      class << self
+        # board has no default. Supplying one would mean either packaging a sample board or reading
+        # from this repo's spec directory, and neither belongs in a shipped gem. MockBoard.load builds
+        # one from the files jirametrics already downloads.
+        def empty board:, created: DEFAULT_CREATED, key: nil, creation_status: nil,
+          current_sprint_ids: nil
+          new(
+            raw: raw_for(
+              created: created,
+              key: key || next_generated_key,
+              creation_status: resolve_creation_status(creation_status, board),
+              current_sprint_ids: current_sprint_ids,
+              board_id: board.id
+            ),
+            board: board
+          )
+        end
+
+        private
+
+        def next_generated_key
+          @next_key_number ||= FIRST_GENERATED_KEY_NUMBER
+          "SP-#{@next_key_number}".tap { @next_key_number += 1 }
+        end
+
+        # A Status carries its category, so the issue cannot end up claiming to be Done while sitting in
+        # To Do. Specs that need a status the board does not have can build one with Status.new, which
+        # is explicit about being artificial rather than being smuggled in as a name and id.
+        def resolve_creation_status creation_status, board
+          return creation_status if creation_status.is_a? Status
+
+          raise "creation_status must be a Status, got #{creation_status.class}" unless creation_status.nil?
+
+          backlog_statuses = board.possible_statuses.find_all_by_name('Backlog')
+          raise 'No Backlog status found' if backlog_statuses.empty?
+
+          backlog_statuses.first
+        end
+
+        # Mimics an issue created directly inside a sprint: that membership lives only in the current
+        # Sprint custom field and never appears as a changelog transition.
+        #
+        # Only two keys are ever read back. Issue#current_sprint_ids takes the ids, and
+        # Issue#sprint_field_id finds the sprint field by looking for an array of hashes carrying a
+        # boardId. Anything else written here would be decoration that could contradict the board.
+        def raw_for created:, key:, creation_status:, current_sprint_ids:, board_id:
+          sprint_field =
+            if current_sprint_ids
+              { 'customfield_10020' => current_sprint_ids.collect { |id| { 'id' => id, 'boardId' => board_id } } }
+            else
+              {}
+            end
+          created_time = JiraMetrics::Testing.to_time(created).to_s
+          {
+            'key' => key,
+            'changelog' => { 'histories' => [] },
+            'fields' => sprint_field.merge(
+              'created' => created_time,
+              'updated' => created_time,
+              'status' => {
+                'name' => creation_status.name,
+                'id' => creation_status.id.to_s,
+                'statusCategory' => {
+                  'name' => creation_status.category.name,
+                  'id' => creation_status.category.id,
+                  'key' => creation_status.category.key
+                }
+              },
+              'priority' => { 'name' => 'Medium', 'id' => '3' },
+              'issuetype' => { 'name' => 'Bug' },
+              'creator' => { 'displayName' => 'Tolkien' },
+              'summary' => 'Do the thing'
+            )
+          }
+        end
+      end
+    end
+  end
+end

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
@@ -94,6 +92,20 @@ class TimeBasedHistogram < TimeBasedChart
     items_hash
   end
 
+  # One cell of the statistics table. A group can survive grouping and still have nothing to plot,
+  # when every item in it was excluded for having no measurable cycle time, and then there are no
+  # statistics to show for it at all. Dashing the cells keeps the group visible: dropping the row
+  # would make it look like the group had never existed.
+  def stats_cell value
+    return '&ndash;' if value.nil?
+
+    block_given? ? yield(value) : value
+  end
+
+  def any_empty_stats? the_stats
+    the_stats.any? { |_label, stats| stats.empty? }
+  end
+
   def stats_for histogram_data:, percentiles:
     return {} if histogram_data.empty?
 

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'
+  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