jirametrics 3.3.1 → 3.5

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

data/lib/jirametrics/flow_efficiency_scatterplot.rb

@@ -12,10 +12,11 @@ class FlowEfficiencyScatterplot < ChartBase
     super()
 
     header_text 'Flow Efficiency'
+    no_data_text '<%= render_header %><div>No data matched the selected criteria. Nothing to show.</div>'
     description_text <<-HTML
       <div class="p">
         This chart shows the active time against the the total time spent on a ticket.
-        <a href="https://improvingflow.com/2024/07/06/flow-efficiency.html">Flow  efficiency</a> is the ratio
+        <a href="https://blog.mikebowler.ca/2024/07/06/flow-efficiency/">Flow  efficiency</a> is the ratio
         between these two numbers.
       </div>
       <div class="p">
@@ -63,10 +64,7 @@ class FlowEfficiencyScatterplot < ChartBase
       create_dataset(issues: issues, label: rules.label, color: rules.color)
     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/html/aging_work_in_progress_chart.erb

@@ -42,21 +42,24 @@ new Chart(document.getElementById(<%= chart_id.inspect %>).getContext('2d'),
           z: 1 // draw the grid lines on top of the bars
         },
         stacked: false,
-        max: <%= (@max_age * 1.1).to_i %>
+        max: <%= (@max_age * 1.1).to_i %>,
+        ticks: {
+          // Uses labelExceptCrowdedCeiling() defined in index.js.
+          callback: labelExceptCrowdedCeiling
+        }
       }
     },
     plugins: {
       tooltip: {
         callbacks: {
           label: function(context) {
-            if( typeof(context.dataset.data[context.dataIndex]) == "number" ) {
-              let full_data = <%= @bar_data.inspect %>;
-              let columnIndex = context.dataIndex;
-              let rowIndex = context.datasetIndex - <%= @row_index_offset %>;
-              return context.dataset.label + " of completed work items left this column in " +full_data[rowIndex][columnIndex] + " days or less";
+            let point = context.dataset.data[context.dataIndex];
+            // A band is a floating bar, [bottom, top]. A dot is an object carrying its own title.
+            if( Array.isArray(point) ) {
+              return context.dataset.label + " of completed work items left this column in " + point[1] + " days or less";
             }
             else {
-              return context.dataset.data[context.dataIndex].title;
+              return point.title;
             }
           }
         }

data/lib/jirametrics/html/cumulative_flow_diagram.erb

@@ -14,6 +14,8 @@ if (!Chart.Tooltip.positioners.legendItem) {
 }
 (function() {
   const hatchWindows = <%= hatch_windows.to_json %>;
+  const annotationDescriptions = <%= date_annotation_hover_data %>;
+  const ANNOTATION_HOVER_TOLERANCE = 6;
 
   // Custom plugin: draws diagonal hatching over correction windows in the affected band.
   // Uses createDiagonalPattern() defined in index.js.
@@ -23,7 +25,7 @@ if (!Chart.Tooltip.positioners.legendItem) {
       // Redraw each correction-window border line so that the gaps between
       // dashes show the band fill colour rather than being transparent.
       // Strategy: draw a solid line in the fill colour first, then the dashed
-      // border line on top. afterDraw (hatching) fires after this, so the
+      // border line on top. The hatching runs straight after this, so the
       // hatch pattern still appears over both lines.
       const ctx = chart.ctx;
       const ca  = chart.chartArea;
@@ -55,8 +57,15 @@ if (!Chart.Tooltip.positioners.legendItem) {
         drawSegment(win.fill_color, []);      // solid fill colour fills the gaps
         drawSegment(win.color,      [6, 4]);  // dashed border colour on top
       });
+
+      // The hatching used to run in afterDraw, which put it above the annotation labels no
+      // matter what drawTime those asked for. Running it here, immediately after the borders,
+      // lets a label drawn at afterDraw land on top of it. The trend lines still draw over the
+      // hatching, since cfdFlowMetricsPlugin.afterDraw runs later than this either way.
+      cfdHatchPlugin.drawHatching(chart);
     },
-    afterDraw: function(chart) {
+    // Not a Chart.js hook. Called explicitly from afterDatasetsDraw above.
+    drawHatching: function(chart) {
       const ctx = chart.ctx;
       const ca  = chart.chartArea;
       hatchWindows.forEach(function(win) {
@@ -203,6 +212,44 @@ if (!Chart.Tooltip.positioners.legendItem) {
       ctx.restore();
     }
 
+    // The description box for whichever annotation the cursor is near. This lives on the overlay
+    // rather than going through chartjs-plugin-annotation's own enter/leave, because those need
+    // Chart.js events and triangle mode switches those off.
+    function drawAnnotationDescription(ctx, chart, fm) {
+      const lines = fm._hoveredAnnotation.lines;
+      if (!lines.length) return;
+
+      const ca = chart.chartArea;
+      ctx.save();
+      ctx.font = '11px sans-serif';
+      const pad = 6, lineHeight = 14;
+      const w = Math.max.apply(null, lines.map(function (l) { return ctx.measureText(l).width; })) + pad * 2;
+      const h = lines.length * lineHeight + pad * 2;
+      // Sit below and right of the cursor, flipping when that would cross the edge of the plot.
+      let x = fm.mouseX + 12;
+      let y = fm.mouseY + 12;
+      if (x + w > ca.right)  x = fm.mouseX - 12 - w;
+      if (y + h > ca.bottom) y = fm.mouseY - 12 - h;
+      ctx.fillStyle = 'rgba(0,0,0,0.85)';
+      ctx.fillRect(x, y, w, h);
+      ctx.fillStyle = '#ffffff';
+      ctx.textAlign = 'left';
+      ctx.textBaseline = 'top';
+      lines.forEach(function (line, i) { ctx.fillText(line, x + pad, y + pad + i * lineHeight); });
+      ctx.restore();
+    }
+
+    function annotationNear(chart, x) {
+      if (x === null) return null;
+
+      let best = null, bestDistance = ANNOTATION_HOVER_TOLERANCE;
+      annotationDescriptions.forEach(function (a) {
+        const distance = Math.abs(chart.scales.x.getPixelForValue(new Date(a.date).getTime()) - x);
+        if (distance <= bestDistance) { bestDistance = distance; best = a; }
+      });
+      return best;
+    }
+
     function drawTriangle(ctx, chart, fm) {
       const ca    = chart.chartArea;
       const ds    = chart.data.datasets;
@@ -312,6 +359,8 @@ if (!Chart.Tooltip.positioners.legendItem) {
         const dates = chart.data.datasets[0].data.map(d => new Date(d.x).getTime());
         chart._flowMetrics = {
           mouseX:      null,
+          mouseY:      null,
+          _hoveredAnnotation: null,
           arrivals,
           departures,
           dates,
@@ -323,9 +372,9 @@ if (!Chart.Tooltip.positioners.legendItem) {
 
         // The triangle is drawn on a separate overlay canvas using native DOM
         // events, completely bypassing Chart.js's render/event cycle (which
-        // behaves unreliably in Safari). The triangle is hidden immediately on
-        // mouse move and redrawn after a short pause (debounce), preventing the
-        // browser from being overwhelmed by rapid redraws.
+        // behaves unreliably in Safari). Redraws are coalesced into a single
+        // requestAnimationFrame (see scheduleOverlayRedraw) so a fast mouse move
+        // cannot queue up more redraws than the browser can paint.
         const dpr     = window.devicePixelRatio || 1;
         const parent = canvas.parentNode;
         if (getComputedStyle(parent).position === 'static') parent.style.position = 'relative';
@@ -359,6 +408,12 @@ if (!Chart.Tooltip.positioners.legendItem) {
         // disabled entirely so its internal hover/tooltip logic cannot interfere
         // with the overlay canvas rAF (which hangs Safari at certain positions).
         // Our native canvas mousemove handler is unaffected by this setting.
+        //
+        // Switching events off wholesale looks heavy handed, and it is. We never found
+        // the root cause of the Safari hang. Other fixes we tried worked in some
+        // browsers but not all; this is the only one that was reliable across Safari,
+        // Chrome, Edge and Firefox. Treat it as load bearing: anything that re-enables
+        // events here has to be retested in all four.
         const defaultEvents = ['mousemove', 'mouseout', 'click', 'touchstart', 'touchmove'];
 
         function setTriangleMode(enabled) {
@@ -386,10 +441,9 @@ if (!Chart.Tooltip.positioners.legendItem) {
           if (fm._rafId !== null) return;
           fm._rafId = requestAnimationFrame(function () {
             fm._rafId = null;
-            if (fm._triangleEnabled) {
-              octx.clearRect(0, 0, cssW, cssH);
-              if (fm.mouseX !== null) drawTriangle(octx, chart, fm);
-            }
+            octx.clearRect(0, 0, cssW, cssH);
+            if (fm._triangleEnabled && fm.mouseX !== null) drawTriangle(octx, chart, fm);
+            if (fm._hoveredAnnotation) drawAnnotationDescription(octx, chart, fm);
           });
         }
 
@@ -399,12 +453,17 @@ if (!Chart.Tooltip.positioners.legendItem) {
           const y = e.clientY - rect.top;
           const ca = chart.chartArea;
           if (!ca) return;
-          fm.mouseX = (x >= ca.left && x <= ca.right && y >= ca.top && y <= ca.bottom) ? x : null;
+          const inside = x >= ca.left && x <= ca.right && y >= ca.top && y <= ca.bottom;
+          fm.mouseX = inside ? x : null;
+          fm.mouseY = inside ? y : null;
+          fm._hoveredAnnotation = annotationNear(chart, fm.mouseX);
           scheduleOverlayRedraw();
         }
 
         function onMouseLeave() {
           fm.mouseX = null;
+          fm.mouseY = null;
+          fm._hoveredAnnotation = null;
           scheduleOverlayRedraw();
         }
 
@@ -458,6 +517,15 @@ if (!Chart.Tooltip.positioners.legendItem) {
         point: { radius: 0 }
       },
       plugins: {
+        // The plugin draws the lines and their static labels. It does NOT get the hover callbacks,
+        // because triangle mode switches Chart.js events off and they would fire only when the
+        // triangle was hidden. The overlay canvas reveals descriptions instead, from the native
+        // mousemove handler, so it behaves the same in both modes.
+        annotation: {
+          annotations: {
+            <%= date_annotation hover: false %>
+          }
+        },
         tooltip: {
           enabled: false,
           position: 'legendItem',

data/lib/jirametrics/html/estimate_accuracy_chart.erb

@@ -6,7 +6,40 @@
 new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
   type: 'bubble',
   data: {
-    datasets: <%= JSON.generate(data_sets) %>
+    datasets: (function() {
+      const dataSets = <%= JSON.generate(data_sets) %>;
+      // The still in progress series is drawn as right pointing arrows rather than discs. Those
+      // items have not finished, so their cycletime is a lower bound that keeps growing and the
+      // arrow says "this one is still moving that way". Same idea as the capped-value arrows on
+      // the scatterplot, turned to point along the axis that is actually still moving.
+      //
+      // Sized per point rather than at a fixed size, because on this chart the radius carries the
+      // number of issues stacked at that spot and we would be throwing that away.
+      function movementArrow(color, radius) {
+        const size = Math.max(12, Math.round(radius * 3));
+        const glyph = document.createElement('canvas');
+        glyph.width = size; glyph.height = size;
+        const pen = glyph.getContext('2d');
+        const middle = size / 2, head = size * 0.3, tip = size * 0.88;
+        pen.strokeStyle = color;
+        pen.lineWidth = Math.max(2, radius * 0.42);
+        pen.lineCap = 'round'; pen.lineJoin = 'round';
+        pen.beginPath();
+        pen.moveTo(size * 0.12, middle); pen.lineTo(tip, middle);
+        pen.moveTo(tip - head, middle - head);
+        pen.lineTo(tip, middle);
+        pen.lineTo(tip - head, middle + head);
+        pen.stroke();
+        return glyph;
+      }
+      dataSets.forEach(function(dataSet) {
+        if (!dataSet.still_in_progress) return;
+        dataSet.pointStyle = dataSet.data.map(function(point) {
+          return movementArrow(dataSet.backgroundColor, point.r);
+        });
+      });
+      return dataSets;
+    })()
   },
   options: {
     responsive: <%= canvas_responsive? %>, // If responsive is true then it fills the screen

data/lib/jirametrics/html/index.css

@@ -106,10 +106,16 @@
   --wip-by-column-chart-limit-line-color: #D55E00;        /* Okabe-Ito vermilion */
   --wip-by-column-chart-recommendation-color: #009E73;    /* Okabe-Ito bluish green */
 
-  --estimate-accuracy-chart-completed-fill-color: #92D9C0;    /* light bluish green */
-  --estimate-accuracy-chart-completed-border-color: #009E73;  /* Okabe-Ito bluish green */
-  --estimate-accuracy-chart-active-fill-color: #F4C6AD;       /* light vermilion */
-  --estimate-accuracy-chart-active-border-color: #D55E00;     /* Okabe-Ito vermilion */
+  /* Full strength, not lightened. The pastel versions of these two collapsed into the same beige
+     under protanopia (4.45 apart, where the palette's own floor is 11.08) and measured 1.6 against
+     white, half the contrast WCAG asks of a shape you need to see. At full strength they are 18.45
+     apart and clear the contrast floor. The border is the page colour rather than a second hue, so
+     it separates overlapping bubbles instead of competing with the fill, and needs no dark mode
+     override. See jirametrics-7ss. */
+  --estimate-accuracy-chart-completed-fill-color: #009E73;    /* Okabe-Ito bluish green */
+  --estimate-accuracy-chart-completed-border-color: var(--body-background);
+  --estimate-accuracy-chart-active-fill-color: #D55E00;       /* Okabe-Ito vermilion */
+  --estimate-accuracy-chart-active-border-color: var(--body-background);
 
   --expedited-chart-no-longer-expedited: gray;
   --expedited-chart-dot-issue-started-color: #E69F00;     /* Okabe-Ito orange */
@@ -315,8 +321,6 @@ html[data-theme="dark"] {
      band. Those are the two ends of the duration ramp, so confusing them is the worst case. This
      stays in the same warm family so the ramp still reads cool to warm as work ages. */
   --wip-chart-duration-more-than-four-weeks-color: #B16BAE;
-  --estimate-accuracy-chart-completed-border-color: #2DCB9A;
-  --estimate-accuracy-chart-active-border-color: #E69F00;
   --expedited-chart-dot-issue-stopped-color: #2DCB9A;
   --expedited-chart-dot-expedite-started-color: #E69F00;
   --expedited-chart-dot-expedite-stopped-color: #2DCB9A;
@@ -481,9 +485,6 @@ html[data-theme="light"] {
     --wip-chart-duration-four-weeks-or-less-color: #D55E00;
     --wip-chart-duration-more-than-four-weeks-color: #B16BAE; /* see jirametrics-3fg */
 
-    --estimate-accuracy-chart-completed-border-color: #2DCB9A;
-    --estimate-accuracy-chart-active-border-color: #E69F00;
-
     --expedited-chart-dot-issue-stopped-color: #2DCB9A;
     --expedited-chart-dot-expedite-started-color: #E69F00;
     --expedited-chart-dot-expedite-stopped-color: #2DCB9A;

data/lib/jirametrics/html/index.js

@@ -157,6 +157,19 @@ function withAlpha(color, alpha) {
   return resolved.replace(/^rgb\(/, 'rgba(').replace(/\)$/, `, ${alpha})`)
 }
 
+// A y-axis tick callback for charts whose ceiling is deliberately set above their tallest value, so
+// you can see that nothing is clipped. Chart.js labels that ceiling too, which gives you an arbitrary
+// number like 169 sitting just above 160, or 62 above 50. Drop that label, unless the ceiling happens
+// to land exactly on the regular grid, in which case it is a perfectly good label and worth keeping.
+// Pass it straight to ticks.callback.
+//   ticks 0 20 .. 160 169 -> 169 dropped, it breaks the spacing
+//   ticks 0 20 .. 100 120 -> 120 kept, it continues the spacing
+function labelExceptCrowdedCeiling(value, index, ticks) {
+  if (index !== ticks.length - 1 || index < 2) return value
+  let regularGap = ticks[index - 1].value - ticks[index - 2].value
+  return value - ticks[index - 1].value === regularGap ? value : null
+}
+
 function createDiagonalPattern(color = 'black') {
   // create a 5x5 px canvas for the pattern's base shape
   let shape = document.createElement('canvas')

data/lib/jirametrics/html/time_based_scatterplot.erb

@@ -82,9 +82,10 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           color: <%= CssVariable['--grid-line-color'].to_json %>
         },
         ticks: {
+          // Uses labelExceptCrowdedCeiling() defined in index.js.
           callback: function(value, index, ticks) {
             <% if @cap %>if (value > <%= @cap[:cutoff] %>) return null;<% end %>
-            return index === ticks.length - 1 ? null : value;
+            return labelExceptCrowdedCeiling(value, index, ticks);
           }
         }
       }

data/lib/jirametrics/issue.rb

@@ -63,7 +63,7 @@ class Issue
 
   def labels = raw_fields['labels'] || []
 
-  def author = raw_fields['creator']&.[]('displayName') || ''
+  def author = User.from_raw(raw_fields['creator'])&.display_name || ''
 
   def resolution = raw_fields['resolution']&.[]('name')
 
@@ -374,13 +374,11 @@ class Issue
     @changes.reverse.find(&:resolution?)
   end
 
-  def assigned_to
-    raw_fields['assignee']&.[]('displayName')
-  end
+  # nil rather than '' when there's no assignee, and daily_view relies on it to decide whether to
+  # render an assignee line at all.
+  def assigned_to = User.from_raw(raw_fields['assignee'])&.display_name
 
-  def assigned_to_icon_url
-    raw_fields['assignee']&.[]('avatarUrls')&.[]('16x16')
-  end
+  def assigned_to_icon_url = User.from_raw(raw_fields['assignee'])&.avatar_url
 
   # Many test failures are simply unreadable because the default inspect on this class goes
   # on for pages. Shorten it up.

data/lib/jirametrics/issue_printer.rb

@@ -19,10 +19,11 @@ class IssuePrinter
   end
 
   def assignee_line
-    assignee = @issue.raw['fields']['assignee']
-    return '' if assignee.nil?
+    user = User.from_raw @issue.raw['fields']['assignee']
+    return '' if user.nil?
 
-    "  [assignee] #{assignee['name'].inspect} <#{assignee['emailAddress']}>\n"
+    email = user.email_address
+    "  [assignee] #{user.display_name.inspect}#{" <#{email}>" if email}\n"
   end
 
   def links_section
@@ -78,6 +79,7 @@ class IssuePrinter
   def render_history history
     type_width = history.collect { |_time, type, _detail, _artificial| type&.length || 0 }.max
     sort_history!(history)
+    # Not all ruby versions return the same string for to_s so we force to a known format.
     history.map do |time, type, detail, _artificial|
       type = type.nil? ? '-' * type_width : type.rjust(type_width)
       "    #{time.strftime '%Y-%m-%d %H:%M:%S %z'} [#{type}] #{detail}\n"

data/lib/jirametrics/jira_gateway.rb

@@ -109,15 +109,13 @@ class JiraGateway
 
   VerifyResult = Data.define(:ok, :url, :message)
 
-  # Confirm that our credentials actually authenticate against Jira. We deliberately hit /myself,
-  # which requires authentication on every Jira edition (anonymous callers get a 401). An endpoint
-  # that also answers anonymously would happily "succeed" with bad credentials, which defeats the
-  # whole point. Cloud speaks v3, Server/Data Center speaks v2. Returns a VerifyResult rather than
-  # raising so the caller can report on every configured connection and set its own exit status.
   def verify_connection
+    # We use /myself because the only reason it can fail is if we aren't authenticated.
     json = call_url relative_url: "/rest/api/#{cloud? ? 3 : 2}/myself"
-    user = json['displayName'] || json['name'] || json['emailAddress'] || 'unknown user'
-    VerifyResult.new(ok: true, url: @jira_url, message: "Verified #{@jira_url} (authenticated as #{user})")
+
+    user = User.new raw: json
+    who = user.display_name || 'unknown user'
+    VerifyResult.new(ok: true, url: @jira_url, message: "Verified #{@jira_url} (authenticated as #{who})")
   rescue StandardError => e
     VerifyResult.new(ok: false, url: @jira_url, message: "Could not authenticate to #{@jira_url}: #{e.message}")
   end

data/lib/jirametrics/project_config.rb

@@ -44,6 +44,7 @@ class ProjectConfig
     load_fix_versions
     load_users
     resolve_blocked_stalled_status_settings
+    report_unusable_date_annotations
   end
 
   def run load_only: false
@@ -79,6 +80,29 @@ class ProjectConfig
   # passed through but that no longer exists in Jira). It fires often -- any workflow rework leaves
   # these behind -- so we say the explanation once and hand over a single ready-to-paste block of
   # mappings rather than one repetitive paragraph per status.
+  # Print one consolidated warning covering every date annotation that has neither a label nor a
+  # description. Such an annotation draws a bare line with nothing to say what it marks, which is
+  # almost always a typo in the config rather than a choice. One warning per project, because the
+  # same settings hash is usually shared across several projects and every chart re-reads it.
+  def report_unusable_date_annotations
+    return if @unusable_date_annotations_reported
+
+    @unusable_date_annotations_reported = true
+
+    unusable = (settings['date_annotations'] || []).reject do |annotation|
+      annotation['label'] || annotation['description']
+    end
+    return if unusable.empty?
+
+    dates = unusable.map { |annotation| annotation['date'].inspect }.join(', ')
+    file_system.warning(
+      "These date annotations have neither a label nor a description: #{dates}. Each will draw " \
+      'a bare line with nothing to say what it marks, which is almost certainly a mistake. Give ' \
+      'each one a label, a description, or both. If a bare line really is what you wanted, they ' \
+      'will work as they are.'
+    )
+  end
+
   def report_fabricated_statuses
     statuses = possible_statuses.fabricated_statuses
     return if statuses.empty? || @fabricated_statuses_reported

data/lib/jirametrics/sprint_burndown.rb

@@ -37,13 +37,13 @@ class SprintBurndown < ChartBase
   end
 
   def run
-    return nil unless current_board.scrum?
+    return render_no_data unless current_board.scrum?
 
     sprints = sprints_in_time_range current_board
     change_data_by_sprint = gather_change_data_by_sprint sprints
 
     result = +''
-    result << render_top_text(binding)
+    result << render_top_text
 
     # HashEachMethods misreads this array of [method, title] pairs as a hash and thinks y_axis_title
     # is unused; in fact the ERB template reads it (and data_method) from the binding we pass to render.