jirametrics 3.3.1 → 3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a2003eb5e447333b282b856e553c7f3f68792da373ce3b563c7f9e4e56dec45
-  data.tar.gz: 50b443fbcad6fe9dff8b247a7e0662cfed8c41724bb1e8dbd5d17c33a58ff416
+  metadata.gz: 1f7292394330330ca10f89a28f02fab3e95cff385736c423ca3602c23551e4ca
+  data.tar.gz: 4690b5ce8cc47d3e980ee026e68f6f245e564ec51aa914914dd7a0db32f3c0b2
 SHA512:
-  metadata.gz: bdaa2c39f21752d0a1a815dc39dd10235cea508f873d89a32d722ea5db4d0d59eef1738febdffde062eaa31cb9b8c24598e2e0b96ccce478a296fe255c0b7997
-  data.tar.gz: 8a9013ed9d3bd5ebef3d2a70c1b870ec5624125d0f2fb5989d375e4d005b7259646d66b24d9babcf49d794671dbc65505770b16c5438624406e4dd21e182b98a
+  metadata.gz: 6f32fbe86ecfb9ecc5ce7ace7d0a2971b6777c7a61e4513d41d2444a976699487ba4da415b6e84484cad72a45ee6af4a822f14da430018e6b40b39bb48046a70
+  data.tar.gz: 2b4af2fe6c95834710901e3aacccc1d260ceb7c28020a853f1a643be1faf3c48a0663488839c522249e2a14a2d3c6e4665425a3c7bf5175354a0311493679ee6

data/lib/jirametrics/aging_work_bar_chart.rb

@@ -14,6 +14,7 @@ class AgingWorkBarChart < ChartBase
     @percentage_lines = [] # Populated by run; the description reads it, so it must never be nil.
     percentiles [85]
     header_text 'Aging Work Bar Chart'
+    no_data_text '<%= render_header %><p>There is no aging work</p>'
     # div class="p" throughout rather than <p>: color_block emits a div and the list below is an
     # ol, neither of which is legal inside a paragraph. A browser closes the p at the first one,
     # which strands the rest of the text outside it. This is what the other charts use.
@@ -69,10 +70,7 @@ class AgingWorkBarChart < ChartBase
       { percentile: percentile, days: days, x: date_range.end - days, id: "percentile_#{percentile}" }
     end
 
-    if aging_issues.empty?
-      @description_text = '<p>There is no aging work</p>'
-      return render_top_text(binding)
-    end
+    return render_no_data if aging_issues.empty?
 
     wrap_and_render(binding, __FILE__)
   end

data/lib/jirametrics/aging_work_in_progress_chart.rb

@@ -12,7 +12,7 @@ class AgingWorkInProgressChart < ChartBase
 
   def initialize block
     super()
-    header_text 'Aging Work in Progress'
+    header_text 'Aging Work in Progress on board: <%= current_board.name %>'
     # div class="p" rather than <p>: the notes below are a ul, which is block level and not legal
     # inside a paragraph, so a browser closes the p early. Harmless while the list is the last
     # thing in the block, but it breaks the moment any text follows it.
@@ -59,7 +59,6 @@ class AgingWorkInProgressChart < ChartBase
   def run
     determine_board_columns
 
-    @header_text += " on board: #{current_board.name}"
     data_sets = make_data_sets
 
     adjust_visibility_of_unmapped_status_column data_sets: data_sets
@@ -91,17 +90,27 @@ class AgingWorkInProgressChart < ChartBase
 
     rules_to_issues = group_issues aging_issues
     data_sets = rules_to_issues.keys.collect { |rules| line_data_set(rules, rules_to_issues[rules]) }
-    # The y-axis is scaled to the oldest item, but never shorter than 20 days.
-    @max_age = data_sets.flat_map { |set| set['data'].collect { |point| point['y'] } }.push(20).max
 
     calculator = BoardMovementCalculator.new board: @all_boards[@board_id], issues: issues, today: date_range.end
     column_indexes_to_remove = trim_board_columns data_sets: data_sets, calculator: calculator
-    @row_index_offset = data_sets.size
 
     append_bar_data_sets data_sets, calculator, column_indexes_to_remove
+    @max_age = highest_plotted_age data_sets
     data_sets
   end
 
+  # The y-axis ceiling is set a little above this so you can see that the tallest thing on the chart
+  # really does stop where it stops, rather than being clipped by the top of the plot. Bands count as
+  # much as dots do. Never shorter than 20 days.
+  # Called after the columns have been trimmed, so a column nobody can see can't push the ceiling up
+  # and leave unexplained space at the top.
+  def highest_plotted_age data_sets
+    data_sets.flat_map do |set|
+      # A dot is {x:, y:, title:}. A band is a floating bar, [bottom, top].
+      set['data'].collect { |point| point.is_a?(Hash) ? point['y'] : point.last }
+    end.push(20).max
+  end
+
   def aging_issue_on_board? issue
     issue.board.id == @board_id && issue.board.cycletime.in_progress?(issue)
   end
@@ -128,32 +137,23 @@ class AgingWorkInProgressChart < ChartBase
     end
   end
 
+  # Each band is a floating bar running from the previous percentile's age up to its own, so it
+  # carries its own absolute position. Asking Chart.js to stack the bands instead hands it the
+  # positioning of every dataset on the chart, and it will stack the aging dots right along with them.
   def append_bar_data_sets data_sets, calculator, column_indexes_to_remove
-    bar_data = []
-    calculator.stacked_age_data_for(percentages: @percentiles.keys).each do |percentage, data|
-      column_indexes_to_remove.reverse_each { |index| data.delete_at index }
+    previous_ages = []
+
+    @percentiles.keys.sort.each do |percentage|
+      ages = calculator.age_data_for percentage: percentage
+      column_indexes_to_remove.reverse_each { |index| ages.delete_at index }
+
       data_sets << {
         'type' => 'bar', 'label' => "#{percentage}%", 'barPercentage' => 1.0, 'categoryPercentage' => 1.0,
-        'backgroundColor' => @percentiles[percentage], 'data' => data
+        'backgroundColor' => @percentiles[percentage],
+        'data' => ages.each_with_index.collect { |age, index| [previous_ages[index] || 0, age] }
       }
-      bar_data << data
+      previous_ages = ages
     end
-    @bar_data = adjust_bar_data bar_data
-  end
-
-  def adjust_bar_data input
-    return [] if input.empty?
-
-    row_size = input.first.size
-
-    output = []
-    output << input.first
-    input.drop(1).each do |row|
-      previous_row = output.last
-      output << 0.upto(row_size - 1).collect { |i| row[i] + previous_row[i] }
-    end
-
-    output
   end
 
   def indexes_of_leading_and_trailing_zeros list

data/lib/jirametrics/atlassian_document_format.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cgi'
+
 class AtlassianDocumentFormat
   attr_reader :users
 
@@ -10,7 +12,7 @@ class AtlassianDocumentFormat
 
   def to_html input
     if input.is_a? String
-      input
+      escape(input)
         .gsub(/{color:(#\w{6})}([^{]+){color}/, '<span style="color: \1">\2</span>') # Colours
         # rubocop:disable Style/PerlBackrefs -- in a gsub block $1 reads cleaner than Regexp.last_match[:...]
         .gsub(/\[~accountid:([^\]]+)\]/) { expand_account_id $1 } # Tagged people
@@ -52,22 +54,22 @@ class AtlassianDocumentFormat
         [Time.at(node_attrs['timestamp'].to_i / 1000, in: @timezone_offset).to_date.to_s, nil]
       when 'decisionItem', 'listItem'  then ['<li>', '</li>']
       when 'decisionList'              then ['<div>Decisions<ul>', '</ul></div>']
-      when 'emoji', 'status'           then [node_attrs['text'], nil]
-      when 'expand'                    then ["<div>#{node_attrs['title']}</div>", nil]
+      when 'emoji', 'status'           then [escape(node_attrs['text']), nil]
+      when 'expand'                    then ["<div>#{escape node_attrs['title']}</div>", nil]
       when 'hardBreak'                 then ['<br />', nil]
       when 'heading'
         level = node_attrs['level']
         ["<h#{level}>", "</h#{level}>"]
       when 'inlineCard'
-        url = node_attrs['url']
+        url = escape node_attrs['url']
         ["[Inline card]: <a href='#{url}'>#{url}</a>", nil]
       when 'media'
-        text = node_attrs['alt'] || node_attrs['id']
+        text = escape(node_attrs['alt'] || node_attrs['id'])
         ["Media: #{text}", nil]
       when 'mediaSingle', 'mediaGroup' then ['<div>', '</div>']
-      when 'mention'                   then ["<b>#{node_attrs['text']}</b>", nil]
+      when 'mention'                   then ["<b>#{escape node_attrs['text']}</b>", nil]
       when 'orderedList'               then ['<ol>', '</ol>']
-      when 'panel'                     then ["<div>#{node_attrs['panelType'].upcase}</div>", nil]
+      when 'panel'                     then ["<div>#{escape node_attrs['panelType'].upcase}</div>", nil]
       when 'paragraph'                 then ['<p>', '</p>']
       when 'rule'                      then ['<hr />', nil]
       when 'table'                     then ['<table>', '</table>']
@@ -76,13 +78,13 @@ class AtlassianDocumentFormat
       when 'tableRow'                  then ['<tr>', '</tr>']
       when 'text'
         marks = adf_marks_to_html(n['marks'])
-        [marks.collect(&:first).join + n['text'], marks.collect(&:last).join]
+        [marks.collect(&:first).join + escape(n['text']), marks.collect(&:last).join]
       when 'taskItem'
         state = node_attrs['state'] == 'TODO' ? '☐' : '☑'
         ["<li>#{state} ", '</li>']
       when 'taskList' then ["<ul class='taskList'>", '</ul>']
       else
-        ["<p>Unparseable section: #{n['type']}</p>", nil]
+        ["<p>Unparseable section: #{escape n['type']}</p>", nil]
       end
     end
   end
@@ -135,11 +137,11 @@ class AtlassianDocumentFormat
     list.filter_map do |mark|
       type = mark['type']
       if type == 'textColor'
-        color = mark['attrs']['color']
+        color = escape mark['attrs']['color']
         ["<span style='color: #{color}'>", '</span>']
       elsif type == 'link'
-        href = mark['attrs']['href']
-        title = mark['attrs']['title']
+        href = escape mark['attrs']['href']
+        title = escape mark['attrs']['title']
         ["<a href='#{href}' title='#{title}'>", '</a>']
       else
         line = mappings.find { |key, _open, _close| key == type }
@@ -150,13 +152,19 @@ class AtlassianDocumentFormat
 
   def expand_account_id account_id
     user = @users.find { |u| u.account_id == account_id }
-    text = account_id
-    text = "@#{user.display_name}" if user
+    text = escape account_id
+    text = "@#{escape user.display_name}" if user
     "<span class='account_id'>#{text}</span>"
   end
 
   private
 
+  # The only markup in the output should be markup this class generated. Everything that comes out
+  # of the document is data written by whoever raised the issue, so it gets escaped on the way past.
+  def escape value
+    CGI.escapeHTML value.to_s
+  end
+
   def adf_node_render node, &render_node
     prefix, suffix = yield(node)
     result = +(prefix || '')

data/lib/jirametrics/board_movement_calculator.rb

@@ -22,29 +22,6 @@ class BoardMovementCalculator
     columns.each_cons(2).any? { |previous, current| current < previous }
   end
 
-  def stacked_age_data_for percentages:
-    data_list = percentages.sort.collect do |percentage|
-      [percentage, age_data_for(percentage: percentage)]
-    end
-
-    stack_data data_list
-  end
-
-  def stack_data data_list
-    remainder = nil
-    data_list.collect do |percentage, data|
-      unless remainder.nil?
-        data = (0...data.length).collect do |i|
-          data[i] - remainder[i]
-        end
-
-      end
-      remainder = data
-
-      [percentage, data]
-    end
-  end
-
   def age_data_for percentage:
     data = []
     board.visible_columns.each_with_index do |_column, column_index|

data/lib/jirametrics/change_item.rb

@@ -37,13 +37,10 @@ class ChangeItem
     raw_value.to_s.split(', ').collect(&:to_i)
   end
 
-  def author
-    @author_raw&.[]('displayName') || @author_raw&.[]('name') || 'Unknown author'
-  end
+  # It should be impossible to have no author at all, but we've seen it in production.
+  def author = User.from_raw(@author_raw)&.display_name || 'Unknown author'
 
-  def author_icon_url
-    @author_raw&.[]('avatarUrls')&.[]('16x16')
-  end
+  def author_icon_url = User.from_raw(@author_raw)&.avatar_url
 
   def artificial? = @artificial
   def assignee? = (field == 'assignee')
@@ -129,8 +126,7 @@ class ChangeItem
   private
 
   def time_to_s time
-    # MRI and JRuby return different strings for to_s() so we have to explicitly provide a full
-    # format so that tests work under both environments.
+    # Not all ruby versions return the same string for to_s so we force to a known format.
     time.strftime '%Y-%m-%d %H:%M:%S %z'
   end
 end

data/lib/jirametrics/chart_base.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
+# require_all cannot resolve an include the way it resolves a superclass, and chart_format.rb
+# sorts after this file, so name it explicitly.
+require_relative 'chart_format'
+
 class ChartBase
+  include ChartFormat
+
   # Okabe-Ito palette - perceptually distinct under the most common forms of colour blindness.
   # Ordered from most- to least-commonly useful for chart series.
   OKABE_ITO_PALETTE = %w[
@@ -63,17 +69,44 @@ class ChartBase
     erb.result(caller_binding)
   end
 
-  def render_top_text caller_binding
-    result = +''
-    result << "<h1 class='foldable'>#{@header_text}</h1>" if @header_text
-    result << ERB.new(@description_text).result(caller_binding) if @description_text
+  # A fresh scope for every template expansion. self is still the chart, so instance variables and
+  # methods are reachable from a template, but the caller's local variables are not. That is the
+  # point: ERB#result assigns its output buffer into whatever binding you hand it, so two templates
+  # sharing one scope silently discard each other's output when one renders the other.
+  def render_binding = binding
+
+  def expand_template text
+    ERB.new(text).result(render_binding)
+  end
+
+  # The header as the reader sees it. Stitch configs match on this through grab_by_title, so it has
+  # to be the expanded text rather than the template.
+  def expanded_header_text = @header_text.nil? ? '' : expand_template(@header_text)
+
+  def render_header
+    return '' unless @header_text
+
+    "<h1 class='foldable'>#{expanded_header_text}</h1>"
+  end
+
+  def render_top_text
+    result = +render_header
+    result << expand_template(@description_text) if @description_text
     result
   end
 
+  # What a chart shows when it has nothing to show. Empty means show nothing at all, not even the
+  # header, which is what a chart that simply does not apply to this board wants.
+  def render_no_data
+    return '' if @no_data_text.nil? || @no_data_text.empty?
+
+    expand_template @no_data_text
+  end
+
   # Render the file and then wrap it with standard headers and quality checks.
   def wrap_and_render caller_binding, file
     result = +''
-    result << render_top_text(caller_binding)
+    result << render_top_text
     result << render(caller_binding, file)
     result
   end
@@ -240,20 +273,16 @@ class ChartBase
     end
   end
 
-  def chart_format object
-    if object.is_a? Time
-      # "2022-04-09T11:38:30-07:00"
-      object.strftime '%Y-%m-%dT%H:%M:%S%z'
-    else
-      object.to_s
-    end
-  end
-
   def header_text text = :none
     @header_text = text unless text == :none
     @header_text
   end
 
+  def no_data_text text = :none
+    @no_data_text = text unless text == :none
+    @no_data_text
+  end
+
   def description_text text = :none
     @description_text = text unless text == :none
     @description_text
@@ -412,7 +441,7 @@ class ChartBase
   # reassemble the report. Generated because only the start/end word differs.
   %w[start end].each do |position|
     define_method "seam_#{position}" do |type = 'chart'|
-      "\n<!-- seam-#{position} | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->\n"
+      "\n<!-- seam-#{position} | chart#{@@chart_counter} | #{self.class} | #{expanded_header_text} | #{type} -->\n"
     end
   end
 

data/lib/jirametrics/chart_format.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Formats values for a Chart.js axis. Included by ChartBase and by the specs, which build the same
+# strings to assert against.
+module ChartFormat
+  def chart_format object
+    # Not all ruby versions return the same string for to_s so we force to a known format.
+
+    if object.is_a? Time
+      object.strftime '%Y-%m-%dT%H:%M:%S%z' # => 2022-04-09T11:38:30-0700
+    else
+      object.to_s
+    end
+  end
+end

data/lib/jirametrics/daily_view.rb

@@ -7,9 +7,10 @@ class DailyView < ChartBase
     super()
 
     header_text 'Daily View'
+    no_data_text '<%= render_header %><div>There are no items currently in progress</div>'
     description_text <<-HTML
       <div class="p">
-        This view shows all the items (<%= aging_issues.count %>) you'll want to discuss during your daily
+        This view shows all the items (<%= @aging_issues.count %>) you'll want to discuss during your daily
         coordination meeting
         (aka daily scrum, standup), in the order that you should be discussing them. The most important
         items are at the top, and the least at the bottom.
@@ -22,15 +23,13 @@ class DailyView < ChartBase
   end
 
   def run
-    aging_issues = select_aging_issues
+    @aging_issues = select_aging_issues
 
-    if aging_issues.empty?
-      return "<h1 class='foldable'>#{@header_text}</h1><div>There are no items currently in progress</div>"
-    end
+    return render_no_data if @aging_issues.empty?
 
     result = +''
-    result << render_top_text(binding)
-    aging_issues.each do |issue|
+    result << render_top_text
+    @aging_issues.each do |issue|
       result << render_issue(issue, child: false)
     end
     result

data/lib/jirametrics/daily_wip_by_parent_chart.rb

@@ -14,7 +14,7 @@ class DailyWipByParentChart < DailyWipChart
         indication of how focused we are on higher level objectives. If there are many parent
         tickets in progress at the same time, either this team has their focus scattered or we
         aren't doing a good job of
-        <a href="https://improvingflow.com/2024/02/21/slicing-epics.html">splitting those parent
+        <a href="https://blog.mikebowler.ca/2024/02/21/slicing-epics/">splitting those parent
         tickets</a>. Neither of those is desirable.
       </div>
       <div class="p">

data/lib/jirametrics/data_quality_report.rb

@@ -63,11 +63,10 @@ class DataQualityReport < ChartBase
     scan_for_issues_on_multiple_boards entries: @entries
 
     entries_with_problems = entries_with_problems()
-    return '' if entries_with_problems.empty?
+    return render_no_data if entries_with_problems.empty?
 
-    caller_binding = binding
     result = +''
-    result << render_top_text(caller_binding)
+    result << render_top_text
 
     result << '<ul class="quality_report">'
     result << render_problem_type(:discarded_changes)
@@ -111,6 +110,7 @@ class DataQualityReport < ChartBase
 
   # Return a format that's easier to assert against
   def testable_entries
+    # Not all ruby versions return the same string for to_s so we force to a known format.
     formatter = ->(time) { time&.strftime('%Y-%m-%d %H:%M:%S %z') || '' }
     @entries.collect do |entry|
       [

data/lib/jirametrics/dependency_chart.rb

@@ -67,6 +67,7 @@ class DependencyChart < ChartBase
     }
 
     header_text 'Dependencies'
+    no_data_text '<%= render_header %><div>No data matched the selected criteria. Nothing to show.</div>'
     description_text <<-HTML
       <p>
         These are all the "linked issues" as defined in Jira
@@ -83,13 +84,10 @@ class DependencyChart < ChartBase
     instance_eval(&@rules_block) if @rules_block
 
     dot_graph = build_dot_graph
-    if dot_graph.nil?
-      return "<h1 class='foldable'>#{@header_text}</h1>" \
-        '<div>No data matched the selected criteria. Nothing to show.</div>'
-    end
+    return render_no_data if dot_graph.nil?
 
     svg = restore_css_variables execute_graphviz(dot_graph.join("\n"))
-    "<h1 class='foldable'>#{@header_text}</h1><div>#{@description_text}#{shrink_svg svg}</div>"
+    "#{render_top_text}<div>#{shrink_svg svg}</div>"
   end
 
   def link_rules &block

data/lib/jirametrics/estimate_accuracy_chart.rb

@@ -14,17 +14,24 @@ class EstimateAccuracyChart < ChartBase
         The #{color_block '--estimate-accuracy-chart-completed-fill-color'} completed dots indicate
         cycletimes.
         <% if @has_aging_data %>
-          The #{color_block '--estimate-accuracy-chart-active-fill-color'} aging dots
+          The #{color_block '--estimate-accuracy-chart-active-fill-color'} aging arrows
           (click on the legend to turn them on) show the current
-          age of items, which will give you a hint as to where they might end up. If they're already
-          far to the right then you know you have a problem.
+          age of items, which will give you a hint as to where they might end up. They point right
+          because those items haven't finished yet, so every one of them will keep moving that way
+          until it does. If they're already far to the right then you know you have a problem.
         <% end %>
       </div>
       <% if @correlation_coefficient %>
         <div class="p">
           The completed items here have a correlation coefficient of <b><%= @correlation_coefficient.round(3) %></b>.
           The closer it is to +1, the stronger the positive correlation. The closer it is to -1,
-          the stronger the negative collalation. Zero would mean no correlation at all.
+          the stronger the negative correlation. Zero would mean no correlation at all.
+        </div>
+      <% elsif @estimates_are_numeric == false %>
+        <div class="p">
+          There's no correlation coefficient here because these estimates are categories rather than
+          numbers. Working one out means measuring the gaps between values, and there's no defined
+          gap between one category and the next, so any number we showed you would be invented.
         </div>
       <% end %>
     HTML
@@ -46,14 +53,15 @@ class EstimateAccuracyChart < ChartBase
     end
     data_sets = scan_issues
 
-    return '' if data_sets.empty?
+    return render_no_data if data_sets.empty?
 
     wrap_and_render(binding, __FILE__)
   end
 
   def scan_issues
     completed_hash, aging_hash = split_into_completed_and_aging issues: issues
-    @correlation_coefficient = correlation_coefficient(completed_hash) unless completed_hash.empty?
+    @estimates_are_numeric = numeric_estimates? completed_hash
+    @correlation_coefficient = correlation_coefficient(completed_hash) if @estimates_are_numeric
     estimation_units = current_board.estimation_configuration.units
     @has_aging_data = !aging_hash.empty?
 
@@ -77,7 +85,7 @@ class EstimateAccuracyChart < ChartBase
         {
           'x' => cycle_time,
           'y' => estimate,
-          'r' => values.size * 2,
+          'r' => bubble_radius(values.size),
           'title' => title
         }
       end
@@ -90,11 +98,23 @@ class EstimateAccuracyChart < ChartBase
         'showLine' => false,
         'backgroundColor' => fill_color,
         'borderColor' => border_color,
-        'hidden' => starts_hidden
+        'hidden' => starts_hidden,
+        # The active series is drawn as right pointing arrows rather than discs, because its
+        # cycletime is a lower bound that keeps growing. The erb needs to know which one that is.
+        'still_in_progress' => completed_or_active == 'active'
       }
     end
   end
 
+  # Chart.js sizes a bubble by its radius but the eye reads it by area, so the radius has
+  # to go as the square root of the count. This multiplier is the radius of a single issue
+  # and everything else scales up from there.
+  SINGLE_ISSUE_RADIUS = 4
+
+  def bubble_radius issue_count
+    (SINGLE_ISSUE_RADIUS * Math.sqrt(issue_count)).round 1
+  end
+
   def estimate_label estimate:, estimation_units:
     if @y_axis_type == 'linear'
       if estimation_units == :story_points
@@ -183,6 +203,15 @@ class EstimateAccuracyChart < ChartBase
 
   # Correlation coefficient is calculated using the Pearson Correlation Coefficient
   # r = Σ((xi - x̄)(yi - ȳ)) / sqrt(Σ(xi - x̄)² · Σ(yi - ȳ)²)
+  # A Pearson coefficient is arithmetic on the distances between values, so it needs a scale where
+  # those distances mean something. T-shirt sizes are ordered but not spaced: nothing says the gap
+  # from M to L matches the gap from S to M. Summing them used to raise and take the export with it.
+  def numeric_estimates? completed_hash
+    return false if completed_hash.empty?
+
+    completed_hash.keys.all? { |estimate, _cycle_time| estimate.is_a? Numeric }
+  end
+
   def correlation_coefficient completed_hash
     list1 = []
     list2 = []

data/lib/jirametrics/expedited_chart.rb

@@ -24,12 +24,13 @@ class ExpeditedChart < ChartBase
     super()
 
     header_text 'Expedited work'
+    no_data_text '<%= render_header %><div>There is no expedited work in this time period.</div>'
     description_text <<-HTML
       <div class="p">
         This chart only shows issues that have been expedited at some point. We care about these as
         any form of expedited work will affect the entire system and will slow down non-expedited work.
         Refer to this article on
-        <a href="https://improvingflow.com/2021/06/16/classes-of-service.html">classes of service</a>
+        <a href="https://blog.mikebowler.ca/2021/06/16/classes-of-service/">classes of service</a>
         for a longer explanation on why we want to avoid expedited work.
       </div>
       <div class="p">
@@ -49,11 +50,9 @@ class ExpeditedChart < ChartBase
       make_expedite_lines_data_set(issue: issue, expedite_data: prepare_expedite_data(issue))
     end
 
-    if data_sets.empty?
-      '<h1 class="foldable">Expedited work</h1><div>There is no expedited work in this time period.</div>'
-    else
-      wrap_and_render(binding, __FILE__)
-    end
+    return render_no_data if data_sets.empty?
+
+    wrap_and_render(binding, __FILE__)
   end
 
   def prepare_expedite_data issue

data/lib/jirametrics/exporter.rb

@@ -6,6 +6,30 @@ class Exporter
   attr_reader :project_configs
   attr_accessor :file_system
 
+  # Nothing in examples/ is loaded with the rest of the library, because an example is something you
+  # opt into rather than something the product provides. Each file there defines the method named
+  # after it. Derived from the directory rather than listed, so a new example is covered by existing.
+  EXAMPLE_NAMES = Dir[File.join(__dir__, 'examples', '*.rb')]
+    .collect { |file| File.basename(file, '.rb').to_sym }
+    .freeze
+
+  # Deliberately method_missing rather than stub methods that the real ones overwrite. Stubs depend
+  # on this file loading before the example, which require_all does not guarantee, and when it lost
+  # that race the stub replaced the working method.
+  def method_missing name, *args, **keywords, &block
+    return super unless EXAMPLE_NAMES.include? name
+
+    raise "#{name} is an example rather than part of jirametrics, so your config has to ask for " \
+      "it. Add this line to the top of your config file:\n\n" \
+      "  require 'jirametrics/examples/#{name}'\n"
+  end
+
+  # These are not things we respond to. Calling one raises, so respond_to? should say false and the
+  # message above should be the only way anyone learns they exist.
+  def respond_to_missing? name, include_private = false
+    super
+  end
+
   def self.logfile_name
     @logfile_name ||= 'jirametrics.log'
   end