jirametrics 3.1.1 → 3.3

data/lib/jirametrics/exporter.rb

@@ -257,35 +257,89 @@ class Exporter
 
   def info key, name_filter:
     selected = []
+    searched = []
     file_system.log_only = true
     each_project_config(name_filter: name_filter) do |project|
       project.evaluate_next_level
 
       project.run load_only: true
-      selected.concat matching_issues_in(project, key)
+      matches = matching_issues_in(project, key)
+      searched << describe_search(project: project, matches: matches.size)
+      selected.concat matches
     rescue => e # rubocop:disable Style/RescueStandardError
       # This happens when we're attempting to load an aggregated project because it hasn't been
       # properly initialized. Since we don't care about aggregated projects, we just ignore it.
       raise unless e.message.start_with? 'This is an aggregated project and issues should have been included'
+
+      searched << "  #{project.name.inspect}: skipped, this is an aggregated project"
     end
     file_system.log_only = false
 
+    report_info_results key: key, selected: selected, where_we_looked: describe_where_we_looked(key, searched)
+  end
+
+  # Verbose in the log, sparse in the terminal. Where we looked is almost always what you need when
+  # an issue you know was downloaded cannot be found, and it is noise the rest of the time.
+  def describe_where_we_looked key, searched
+    return "Searched these projects for #{key.inspect}:\n#{searched.join "\n"}" unless searched.empty?
+
+    'No project configurations were searched at all. Either none are defined in the config file ' \
+      'or none of them matched the name filter.'
+  end
+
+  def report_info_results key:, selected:, where_we_looked:
     if selected.empty?
-      file_system.log "No issues found to match #{key.inspect}"
-    else
-      selected.each do |project, issue|
-        file_system.log "\nProject #{project.name}", also_write_to_stderr: true
-        file_system.log issue.dump, also_write_to_stderr: true
-      end
+      file_system.log(
+        "No issues found to match #{key.inspect}", more: where_we_looked, also_write_to_stderr: true
+      )
+      return
+    end
+
+    file_system.log where_we_looked
+    selected.each do |project, issue, ignored|
+      file_system.log "\nProject #{project.name}", also_write_to_stderr: true
+      file_system.log(IGNORED_ISSUE_NOTE, also_write_to_stderr: true) if ignored
+      file_system.log issue.dump, also_write_to_stderr: true
     end
   end
 
+  # Only the unexpected case is announced. Not being filtered is the common one, and saying so
+  # every time would be noise on top of the dump that was actually asked for. Note the claim is
+  # about the filter, not about charts: an issue that survives filtering may still be absent from
+  # a given chart for its own reasons, so there is no matching note for the other case.
+  IGNORED_ISSUE_NOTE = 'IGNORED by a filter such as ignore_types or ignore_issues. No chart uses it.'
+
+  # One line per project saying where its issues were read from and what was there, so that a
+  # missing issue can be traced to the wrong directory rather than guessed at.
+  def describe_search project:, matches:
+    prefix = project.get_file_prefix raise_if_not_set: false
+    path = prefix.nil? ? '(no file_prefix set)' : File.join(project.target_path.to_s, "#{prefix}_issues")
+    counts =
+      begin
+        collection = project.issues
+        excluded = collection.hidden.size
+        detail = "#{collection.size} issues loaded"
+        detail << ", #{excluded} excluded by filters" if excluded.positive?
+        "#{detail}, #{matches} matched"
+      rescue StandardError
+        'could not be read'
+      end
+    "  #{project.name.inspect}: #{path} (#{counts})"
+  end
+
+  # Asking about a specific issue should always show that issue, whether or not the report used it.
+  # An issue removed by something like ignore_types is exactly when somebody runs info to find out
+  # what happened, and reporting it as missing sends them hunting for a download problem that is
+  # not there. The hidden list is searched first. Returns [project, issue, ignored] triples.
   def matching_issues_in project, key
     matches = []
-    project.issues.each do |issue|
-      matches << [project, issue] if key == issue.key
-      issue.subtasks.each do |subtask|
-        matches << [project, subtask] if key == subtask.key
+    collection = project.issues
+    [[collection.hidden, true], [collection, false]].each do |issues, ignored|
+      issues.each do |issue|
+        matches << [project, issue, ignored] if key == issue.key
+        issue.subtasks.each do |subtask|
+          matches << [project, subtask, ignored] if key == subtask.key
+        end
       end
     end
     matches
@@ -317,9 +371,21 @@ class Exporter
 
   def target_path path = nil
     unless path.nil?
+      previous = @target_path
       @target_path = path
       @target_path += File::SEPARATOR unless @target_path.end_with? File::SEPARATOR
       FileUtils.mkdir_p @target_path
+      # A config is allowed to switch target directories partway through, and when it does, an
+      # issue can be downloaded into one and looked for in another. Recording every change makes
+      # that visible rather than something to guess at. See GitHub issue 77.
+      # The constructor seeds this with a bare '.', and the setter always appends a separator, so
+      # an unseparated '.' is the untouched default rather than something the config chose. Setting
+      # the same path twice is not a change and saying so would be actively misleading.
+      if previous == '.'
+        file_system.diagnostic "target_path set to #{@target_path.inspect}"
+      elsif previous != @target_path
+        file_system.diagnostic "target_path changed from #{previous.inspect} to #{@target_path.inspect}"
+      end
     end
     @target_path
   end

data/lib/jirametrics/groupable_issue_chart.rb

@@ -31,14 +31,39 @@ module GroupableIssueChart
 
       @issue_hints[issue] = rules.issue_hint
       @issue_periods[issue] = rules.last_day_of_period
-      (result[rules] ||= []) << issue
+      accumulate_issue_for_group result, rules, issue
     end
 
     completed_issues.reject! { |issue| ignored_issues.include? issue }
 
     result.each_key do |rules|
-      rules.color = random_color if rules.color.nil?
+      rules.color = next_palette_color if rules.color.nil?
     end
     result
   end
+
+  # Ruby's Hash keeps whichever key object it saw first, so a later issue whose rules object
+  # has different percentiles needs to be reconciled against that retained key rather than
+  # just appended under its own (discarded) key.
+  def accumulate_issue_for_group result, rules, issue
+    existing_key = result.keys.find { |key| key.eql? rules }
+    reconcile_percentiles existing_key, rules if existing_key
+    (result[existing_key || rules] ||= []) << issue
+  end
+
+  # The retained hash key is whichever rules object arrived first, so a later issue setting a
+  # different list would silently lose. That can only be a config error, so say so.
+  def reconcile_percentiles existing_key, rules
+    incoming = rules.percentiles
+    return if incoming.nil?
+
+    existing = existing_key.percentiles
+    if existing.nil?
+      existing_key.percentiles = incoming
+    elsif existing != incoming
+      raise ArgumentError,
+        "group #{existing_key.label.inspect} was given conflicting percentiles: " \
+        "#{existing.inspect} and #{incoming.inspect}"
+    end
+  end
 end

data/lib/jirametrics/grouping_rules.rb

@@ -1,8 +1,20 @@
 # frozen_string_literal: true
 
+require 'jirametrics/percentile_validation'
+
 class GroupingRules < Rules
+  include PercentileValidation
+
   attr_accessor :label, :issue_hint, :label_hint
-  attr_reader :color, :last_day_of_period
+  attr_reader :color, :last_day_of_period, :percentiles
+
+  # nil means "inherit whatever the chart is configured with" and an empty list means "draw no
+  # lines for this group", so neither is validated. Everything else gets the same treatment as
+  # the chart level setter, because these numbers become JavaScript identifiers downstream and a
+  # bad one takes the whole chart out with a syntax error.
+  def percentiles= list
+    @percentiles = list.nil? ? nil : validate_percentiles(list)
+  end
 
   def last_day_of_period= value
     @last_day_of_period = value.is_a?(String) ? Date.parse(value) : value

data/lib/jirametrics/html/aging_work_bar_chart.erb

@@ -40,15 +40,26 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
         annotations: {
           <%= working_days_annotation %>
 
-          <% if percentage_line_x %>
-          line: {
+          <% @percentage_lines.each do |percentage_line| %>
+          <%= percentage_line[:id].to_json %>: {
             type: 'line',
             scaleID: 'x',
-            value: '<%= percentage_line_x %>',
+            value: '<%= percentage_line[:x] %>',
             borderColor: <%= CssVariable.new('--aging-work-bar-chart-percentage-line-color').to_json %>,
             borderWidth: 1,
-            drawTime: 'afterDraw'
-          }
+            hitTolerance: 6,
+            drawTime: 'afterDraw',
+            label: {
+              display: false,
+              content: <%= "#{ordinal percentage_line[:percentile]} percentile of completed work".to_json %>,
+              position: 'start',
+              backgroundColor: 'rgba(0,0,0,0.85)',
+              color: '#fff',
+              font: { size: 11 }
+            },
+            enter(ctx) { ctx.element.label.options.display = true; ctx.chart.draw(); },
+            leave(ctx) { ctx.element.label.options.display = false; ctx.chart.draw(); }
+          },
           <% end %>
         }
       },

data/lib/jirametrics/html/flow_efficiency_scatterplot.erb

@@ -57,7 +57,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           }
           nextVisibility = !!legend.chart.getDatasetMeta(i).hidden;
 
-          // Hide/show the 85% line for that dataset
+          // Hide/show the percentile lines for that dataset
           legend.chart.options.plugins.annotation.annotations["line"+(i/2)].display = nextVisibility;
 
           // Hide/show the trendline for this dataset, if they were enabled. The trendline is always

data/lib/jirametrics/html/index.css

@@ -5,6 +5,22 @@
   --warning-banner: yellow;
 
   --cycletime-scatterplot-overall-trendline-color: gray;
+  --cycletime-scatterplot-cap-rule-color: #555555;
+  --cycletime-scatterplot-cap-gutter-color: rgba(0, 0, 0, 0.05);
+
+  /* Palette for things that need telling apart where no specific colour is wanted. Okabe-Ito,
+     chosen because it stays distinguishable under the common forms of colour vision deficiency.
+     If you need a SPECIFIC colour, configure it rather than relying on whichever slot comes up.
+     Add a slot by defining the next number; the count is read from this file, not hardcoded.
+     These deliberately have no dark mode overrides yet: lightening them for dark backgrounds
+     collapses blue into sky blue, and getting it right needs measuring. See jirametrics-60z. */
+  --palette-color-1: #0072B2;  /* Okabe-Ito blue */
+  --palette-color-2: #E69F00;  /* Okabe-Ito orange */
+  --palette-color-3: #009E73;  /* Okabe-Ito bluish green */
+  --palette-color-4: #56B4E9;  /* Okabe-Ito sky blue */
+  --palette-color-5: #D55E00;  /* Okabe-Ito vermilion */
+  --palette-color-6: #CC79A7;  /* Okabe-Ito reddish purple */
+  --palette-color-7: #F0E442;  /* Okabe-Ito yellow */
 
   --non-working-days-color: #F0F0F0;
   --expedited-color: #D55E00;        /* Okabe-Ito vermilion */
@@ -238,6 +254,8 @@ html[data-theme="dark"] {
   --body-background: #343434;
   --default-text-color: #aaa;
   --grid-line-color: #424242;
+  --cycletime-scatterplot-cap-rule-color: #b8b8b8;
+  --cycletime-scatterplot-cap-gutter-color: rgba(255, 255, 255, 0.08);
   --expedited-color: #E69F00;        /* Okabe-Ito orange for dark bg */
   --blocked-color: #E69F00;          /* Okabe-Ito orange for dark bg */
   --stalled-color: #F0E442;          /* Okabe-Ito yellow - distinct from blocked */
@@ -250,7 +268,14 @@ html[data-theme="dark"] {
   --wip-by-column-chart-limit-line-color: #E69F00;        /* Okabe-Ito orange */
   --wip-by-column-chart-recommendation-color: #2DCB9A;    /* lighter bluish green for dark bg */
   --wip-chart-completed-color: #2DCB9A;                   /* lighter bluish green */
-  --wip-chart-duration-more-than-four-weeks-color: #DE9AC4; /* lighter reddish purple */
+  /* Was inheriting the light #92D9C0, which sat too close to the completed colour above for
+     anyone with protanopia or deuteranopia. Those two mean "completed" and "completed but not
+     started", so they are exactly the pair a reader must separate. See jirametrics-3fg. */
+  --wip-chart-completed-but-not-started-color: #00A062;
+  /* Was #DE9AC4, a lightened reddish purple that collided with the sky blue used for the fastest
+     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;
@@ -262,7 +287,10 @@ html[data-theme="dark"] {
   --sprint-burndown-sprint-color-4: #CC79A7;  /* reddish purple (vermilion → orange conflicts with color-2) */
   --sprint-burndown-sprint-color-5: #F0E442;  /* yellow */
   --sprint-burndown-sprint-color-6: #D55E00;  /* vermilion (sky blue conflicts with color-1) */
-  --sprint-burndown-sprint-color-7: #92D9C0;  /* light teal (yellow conflicts with color-5) */
+  --sprint-burndown-sprint-color-7: #388CF3;  /* lightened blue. Was #92D9C0 light teal, which
+     sat too close to color-3 for anyone with protanopia or deuteranopia. Blue is the one
+     Okabe-Ito hue the dark set was missing, since the original is too dark on this
+     background. See jirametrics-60z for the measurements. */
   --daily-view-selected-issue-background: #474747;
   --daily-view-issue-border: #2DCB9A;
   --daily-view-selected-issue-border: #E69F00;
@@ -294,6 +322,8 @@ html[data-theme="light"] {
   --body-background: white;
   --default-text-color: black;
   --grid-line-color: lightgray;
+  --cycletime-scatterplot-cap-rule-color: #555555;
+  --cycletime-scatterplot-cap-gutter-color: rgba(0, 0, 0, 0.05);
   --expedited-color: #D55E00;        /* Okabe-Ito vermilion */
   --blocked-color: #D55E00;          /* Okabe-Ito vermilion */
   --stalled-color: #E69F00;          /* Okabe-Ito orange */
@@ -377,6 +407,8 @@ html[data-theme="light"] {
     --body-background: #343434;
     --default-text-color: #aaa;
     --grid-line-color: #424242;
+    --cycletime-scatterplot-cap-rule-color: #b8b8b8;
+    --cycletime-scatterplot-cap-gutter-color: rgba(255, 255, 255, 0.08);
 
     --expedited-color: #E69F00;        /* Okabe-Ito orange for dark bg */
     --blocked-color: #E69F00;          /* Okabe-Ito orange for dark bg */
@@ -397,12 +429,12 @@ html[data-theme="light"] {
     --hierarchy-table-inactive-item-text-color: #939393;
 
     --wip-chart-completed-color: #2DCB9A;                   /* lighter bluish green */
-    --wip-chart-completed-but-not-started-color: #92D9C0;
+    --wip-chart-completed-but-not-started-color: #00A062;   /* see jirametrics-3fg */
     --wip-chart-duration-less-than-day-color: #56B4E9;
     --wip-chart-duration-week-or-less-color: #F0E442;
     --wip-chart-duration-two-weeks-or-less-color: #E69F00;
     --wip-chart-duration-four-weeks-or-less-color: #D55E00;
-    --wip-chart-duration-more-than-four-weeks-color: #DE9AC4; /* lighter reddish purple */
+    --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;
@@ -417,7 +449,10 @@ html[data-theme="light"] {
     --sprint-burndown-sprint-color-4: #CC79A7;  /* reddish purple (vermilion → orange conflicts with color-2) */
     --sprint-burndown-sprint-color-5: #F0E442;  /* yellow */
     --sprint-burndown-sprint-color-6: #D55E00;  /* vermilion (sky blue conflicts with color-1) */
-    --sprint-burndown-sprint-color-7: #92D9C0;  /* light teal (yellow conflicts with color-5) */
+    --sprint-burndown-sprint-color-7: #388CF3;  /* lightened blue. Was #92D9C0 light teal, which
+     sat too close to color-3 for anyone with protanopia or deuteranopia. Blue is the one
+     Okabe-Ito hue the dark set was missing, since the original is too dark on this
+     background. See jirametrics-60z for the measurements. */
 
     --daily-view-selected-issue-background: #474747;
     --daily-view-issue-border: #2DCB9A;

data/lib/jirametrics/html/index.erb

@@ -4,9 +4,13 @@
     <title><%= project_name.empty? ? 'JiraMetrics' : "JiraMetrics - #{project_name}" %></title>
     <link rel="icon" type="image/png" href="https://github.com/mikebowler/jirametrics/blob/main/favicon.png?raw=true" />
     <script src="https://cdn.jsdelivr.net/npm/moment@2.29.1/moment.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <!-- Pinned to a major version, not to an exact one: patch and minor releases still arrive
+         automatically, but a new major cannot land in someone's report unannounced. The charts
+         depend on specific annotation plugin behaviour (hitTolerance, enter/leave, the label's own
+         drawTime), and nothing in the test suite reaches browser behaviour to catch a break. -->
+    <script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
     <script src="https://cdn.jsdelivr.net/npm/chartjs-adapter-moment@^1"></script>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/chartjs-plugin-annotation/3.1.0/chartjs-plugin-annotation.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/chartjs-plugin-annotation@3"></script>
     <script type="text/javascript">
 <%= javascript %>
     </script>

data/lib/jirametrics/html/index.js

@@ -141,6 +141,22 @@ window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', eve
 
 // Draw a diagonal pattern to highlight sections of a bar chart. Based on code found at:
 // https://stackoverflow.com/questions/28569667/fill-chart-js-bar-chart-with-diagonal-stripes-or-other-patterns
+// Apply an alpha to a colour that may only be resolvable in the browser, such as one that came
+// from a CSS variable. Ruby cannot do this arithmetic any more now that palette colours are
+// variables rather than literals.
+function withAlpha(color, alpha) {
+  const probe = document.createElement('canvas').getContext('2d')
+  probe.fillStyle = color
+  const resolved = probe.fillStyle  // normalised by the browser to #rrggbb or rgba(...)
+  if (resolved.startsWith('#')) {
+    const r = parseInt(resolved.substr(1, 2), 16)
+    const g = parseInt(resolved.substr(3, 2), 16)
+    const b = parseInt(resolved.substr(5, 2), 16)
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`
+  }
+  return resolved.replace(/^rgb\(/, 'rgba(').replace(/\)$/, `, ${alpha})`)
+}
+
 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_histogram.erb

@@ -36,20 +36,30 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
       annotation: {
         annotations: {
           <%
-            results = the_stats[:all][:percentiles]
-            results.each do |percentile, value|
+            # Guard the nil value: an unlabelled annotation would emit "value:" with nothing after
+            # it, which is a syntax error that takes the whole chart script out.
+            (the_stats.dig(:all, :percentiles) || {}).each do |percentile, value|
+              next if value.nil?
           %>
-          percentile<%= percentile.to_s %>: {
+          <%= "percentile#{percentile}".to_json %>: {
             type: 'line',
             scaleID: 'x',
             value: <%= value %>,
             borderWidth: 1,
+            hitTolerance: 6,
             drawTime: 'beforeDatasetsDraw',
             label: {
-              enabled: true,
-              content: '<%= "#{percentile}%" %>',
+              display: false,
+              content: <%= "#{ordinal percentile} percentile at #{label_cycletime value}".to_json %>,
               position: 'start',
-            }
+              // Drawn late so the label sits on top of the bars rather than behind them.
+              drawTime: 'afterDraw',
+              backgroundColor: 'rgba(0,0,0,0.85)',
+              color: '#fff',
+              font: { size: 11 }
+            },
+            enter(ctx) { ctx.element.label.options.display = true; ctx.chart.draw(); },
+            leave(ctx) { ctx.element.label.options.display = false; ctx.chart.draw(); }
           },
           <% end %>
         },
@@ -83,8 +93,8 @@ if show_stats
         <th>Max</th>
         <th>Avg</th>
         <th>Mode</th>
-        <% percentiles.each do |p| %>
-           <th><%= p %>th</th>
+        <% percentiles.each do |percentile| %>
+           <th><%= ordinal percentile %></th>
         <% end %>
       </tr>
       <% the_stats.each do |k, v| %>
@@ -94,8 +104,8 @@ if show_stats
             <td style="text-align: right;"><%= v[:max] %></td>
             <td style="text-align: right;"><%= sprintf('%.2f', v[:average]) %></td>
             <td><%= v[:mode].join(', ') %></td>
-            <% percentiles.each do |p| %>
-               <td style="text-align: right;"><%= v[:percentiles][p] %></td>
+            <% percentiles.each do |percentile| %>
+               <td style="text-align: right;"><%= v[:percentiles][percentile] %></td>
             <% end %>
           </tr>
        <% end %>
@@ -107,12 +117,14 @@ if show_stats
       <li><b>Min & Max:</b> the observed spread for the data set. Useful to judge how wide the variation is. </li>
       <li><b>Average:</b> the arithmetic mean of the data set. Useful as a <i>"typical representative"</i> of the complete set.</li>
       <li><b>Mode:</b> the most repeated value(s) in the data set. This is the value we're most likely to remember. </li>
-      <li><b>Percentiles:</b> they partition the data set. If X is the Nth percentile, it means that N% of values are X or less. Typical percentiles of interest are:</li>
+      <% unless percentiles.empty? %>
+      <li><b>Percentiles:</b> they partition the data set. If X is the Nth percentile, it means that N% of values are X or less. The ones in the table above:</li>
       <ul>
-        <li><b>50%</b>: also known as the <b>Median</b>. Useful to establish short feedback loops, to monitor that it's not drifting to the right.</li>
-        <li><b>85%</b>: useful to establish service level expectations, accounting for rare events..</li>
-        <li><b>98% (or higher)</b>: useful to gauge worst case expectations..</li>
+        <% percentiles.each do |percentile| %>
+          <li><b><%= percentile %>%</b>: <%= percentile_explanation percentile %></li>
+        <% end %>
       </ul>
+      <% end %>
     </ul>
   </div>
 </div>

data/lib/jirametrics/html/time_based_scatterplot.erb

@@ -5,8 +5,52 @@
 <script>
 new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
   type: 'scatter',
+  <% if @cap %>
+  plugins: [{
+    id: 'capRule<%= chart_id %>',
+    afterDatasetsDraw: function(chart) {
+      const yPixel = chart.scales.y.getPixelForValue(<%= @cap[:sep] %>);
+      const area = chart.chartArea;
+      const pen = chart.ctx;
+      pen.save();
+      pen.strokeStyle = <%= CssVariable['--cycletime-scatterplot-cap-rule-color'].to_json %>;
+      pen.lineWidth = 1.5;
+      [0, 3].forEach(function(offset) {
+        pen.beginPath();
+        pen.moveTo(area.left, yPixel - offset);
+        pen.lineTo(area.right, yPixel - offset);
+        pen.stroke();
+      });
+      pen.restore();
+    }
+  }],
+  <% end %>
   data: {
-    datasets: <%= JSON.generate(data_sets) %>
+    datasets: (function() {
+      const dataSets = <%= JSON.generate(data_sets) %>;
+      <% if @cap %>
+      // draw an up-arrow glyph in the given colour, usable as a Chart.js pointStyle.
+      // The arrow says "the real value continues upward beyond the cap".
+      function capArrow(color) {
+        const size = 18, glyph = document.createElement('canvas');
+        glyph.width = size; glyph.height = size;
+        const pen = glyph.getContext('2d');
+        pen.strokeStyle = color; pen.lineWidth = 2.5; pen.lineCap = 'round'; pen.lineJoin = 'round';
+        pen.beginPath();
+        pen.moveTo(size / 2, size - 3); pen.lineTo(size / 2, 3);
+        pen.moveTo(size / 2 - 5, 8); pen.lineTo(size / 2, 3); pen.lineTo(size / 2 + 5, 8);
+        pen.stroke();
+        return glyph;
+      }
+      dataSets.forEach(function(dataSet) {
+        if (dataSet.type === 'line') return; // skip the interleaved trend lines
+        const arrow = capArrow(dataSet.backgroundColor);
+        dataSet.pointStyle = dataSet.data.map(function(point) { return point.over ? arrow : 'circle'; });
+        dataSet.pointRadius = dataSet.data.map(function(point) { return point.over ? 9 : 3; });
+      });
+      <% end %>
+      return dataSets;
+    })()
   },
   options: {
     title: {
@@ -29,7 +73,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       },
       y: {
         min: 0,
-        max: <%= (@highest_y_value * 1.1).ceil %>,
+        max: <%= @cap ? @cap[:axis_max] : (@highest_y_value * 1.1).ceil %>,
         scaleLabel: {
           display: true
         },
@@ -39,6 +83,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
         },
         ticks: {
           callback: function(value, index, ticks) {
+            <% if @cap %>if (value > <%= @cap[:cutoff] %>) return null;<% end %>
             return index === ticks.length - 1 ? null : value;
           }
         }
@@ -58,15 +103,56 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           <%= working_days_annotation %>
           <%= date_annotation %>
 
-          <% @percentage_lines.each_with_index do |args, index| %>
-          <%   percent, color = args %>
-          line<%= index %>: {
+          <% if @cap %>
+          capGutter: {
+            type: 'box',
+            yMin: <%= @cap[:sep] %>,
+            yMax: <%= @cap[:axis_max] %>,
+            backgroundColor: <%= CssVariable['--cycletime-scatterplot-cap-gutter-color'].to_json %>,
+            borderWidth: 0
+          },
+          capLabel: {
+            type: 'line',
+            yMin: <%= @cap[:sep] %>,
+            yMax: <%= @cap[:sep] %>,
+            borderWidth: 0,
+            drawTime: 'afterDraw',
+            label: {
+              display: true,
+              content: '<%= @cap[:label] %>',
+              position: 'start',
+              yAdjust: 0,
+              backgroundColor: 'rgba(0,0,0,0.85)',
+              color: '#fff',
+              font: { size: 11 }
+            }
+          },
+          <% end %>
+
+          <% @percentage_lines.each do |line| %>
+          <%= line[:id].to_json %>: {
             type: 'line',
-            yMin: <%= percent %>,
-            yMax: <%= percent %>,
-            borderColor: <%= color.to_json %>,
+            yMin: <%= line[:value] %>,
+            yMax: <%= line[:value] %>,
+            borderColor: <%= line[:color].to_json %>,
             borderWidth: 1,
-            drawTime: 'beforeDraw'
+            hitTolerance: 6,
+            drawTime: 'beforeDraw',
+            label: {
+              display: false,
+              <%# to_json rather than quoting by hand: the group label comes from the user's %>
+              <%# grouping_rules block and an apostrophe in it would otherwise end the string. %>
+              content: <%= "#{line[:label]} #{line[:percentile]}% at #{label_days line[:value]}".to_json %>,
+              position: 'end',
+              // The line itself draws early so it sits under the dots, but the hover label has to
+              // draw last or the non-working-day hatching (also beforeDraw) covers it.
+              drawTime: 'afterDraw',
+              backgroundColor: 'rgba(0,0,0,0.85)',
+              color: '#fff',
+              font: { size: 11 }
+            },
+            enter(ctx) { ctx.element.label.options.display = true; ctx.chart.draw(); },
+            leave(ctx) { ctx.element.label.options.display = false; ctx.chart.draw(); }
           },
           <% end %>
         }
@@ -80,8 +166,13 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           }
           nextVisibility = !!legend.chart.getDatasetMeta(i).hidden;
 
-          // Hide/show the 85% line for that dataset
-          legend.chart.options.plugins.annotation.annotations["line"+(i/2)].display = nextVisibility;
+          // Hide/show every percentile line belonging to this group. The map is keyed by the
+          // dataset index we just worked out, which is unambiguous even when two groups share a
+          // label. A group with no lines of its own simply isn't in the map.
+          const annotationMap = <%= legend_annotation_map.to_json %>;
+          (annotationMap[i] || []).forEach((id) => {
+            legend.chart.options.plugins.annotation.annotations[id].display = nextVisibility;
+          });
 
           // Hide/show the trendline for this dataset, if they were enabled. The trendline is always
           // there but not always visible.

data/lib/jirametrics/html_generator.rb

@@ -6,13 +6,32 @@ class HtmlGenerator
   def create_html output_filename:, settings:, project_name: ''
     @settings = settings
     project_name = project_name.to_s
-    html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
     css = load_css html_directory: html_directory
     javascript = file_system.load(File.join(html_directory, 'index.js'))
     erb = ERB.new file_system.load(File.join(html_directory, 'index.erb'))
     file_system.save_file content: erb.result(binding), filename: output_filename
   end
 
+  # Charts allocate colours while they run, which happens before create_html is reached, so the
+  # palette cannot wait for the CSS that create_html loads. It reads the files directly instead.
+  # Deliberately not going through file_system: the shipped stylesheet is part of the gem rather
+  # than user data, and the palette only needs to count slots in it.
+  def color_palette
+    @color_palette ||= ColorPalette.new css: palette_css
+  end
+
+  def palette_css
+    base = File.read File.join(html_directory, 'index.css')
+    extra = settings && settings['include_css']
+    return base unless extra && File.exist?(extra)
+
+    "#{base}\n\n#{File.read extra}"
+  end
+
+  def html_directory
+    "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
+  end
+
   def load_css html_directory:
     base_css_filename = File.join(html_directory, 'index.css')
     base_css = file_system.load(base_css_filename)