jirametrics 2.9 → 2.11

data/lib/jirametrics/data_quality_report.rb

@@ -272,7 +272,7 @@ class DataQualityReport < ChartBase
 
       entry.report(
         problem_key: :items_blocked_on_closed_tickets,
-        detail: "#{entry.issue.key} thinks it's blocked on #{link.other_issue.key}, " \
+        detail: "#{entry.issue.key} thinks it's blocked by #{link.other_issue.key}, " \
           "except #{link.other_issue.key} is closed."
       )
     end

data/lib/jirametrics/downloader.rb

@@ -103,8 +103,6 @@ class Downloader
       json = @jira_gateway.call_url relative_url: '/rest/api/2/search' \
         "?jql=#{escaped_jql}&maxResults=#{max_results}&startAt=#{start_at}&expand=changelog&fields=*all"
 
-      exit_if_call_failed json
-
       json['issues'].each do |issue_json|
         issue_json['exporter'] = {
           'in_initial_query' => initial_query
@@ -139,15 +137,6 @@ class Downloader
     end
   end
 
-  def exit_if_call_failed json
-    # Sometimes Jira returns the singular form of errorMessage and sometimes the plural. Consistency FTW.
-    return unless json['error'] || json['errorMessages'] || json['errorMessage']
-
-    log "Download failed. See #{@file_system.logfile_name} for details.", both: true
-    log "  #{JSON.pretty_generate(json)}"
-    exit 1
-  end
-
   def download_statuses
     log '  Downloading all statuses', both: true
     json = @jira_gateway.call_url relative_url: '/rest/api/2/status'
@@ -188,8 +177,6 @@ class Downloader
     log "  Downloading board configuration for board #{board_id}", both: true
     json = @jira_gateway.call_url relative_url: "/rest/agile/1.0/board/#{board_id}/configuration"
 
-    exit_if_call_failed json
-
     @file_system.save_json(
       json: json,
       filename: File.join(@target_path, "#{file_prefix}_board_#{board_id}_configuration.json")
@@ -213,7 +200,6 @@ class Downloader
     while is_last == false
       json = @jira_gateway.call_url relative_url: "/rest/agile/1.0/board/#{board_id}/sprint?" \
         "maxResults=#{max_results}&startAt=#{start_at}"
-      exit_if_call_failed json
 
       @file_system.save_json(
         json: json,

data/lib/jirametrics/exporter.rb

@@ -64,12 +64,8 @@ class Exporter
     selected = []
     each_project_config(name_filter: name_filter) do |project|
       project.evaluate_next_level
-      # next if project.aggregated_project?
 
       project.run load_only: true
-      project.board_configs.each do |board_config|
-        board_config.run
-      end
       project.issues.each do |issue|
         selected << [project, issue] if keys.include? issue.key
       end
@@ -79,9 +75,13 @@ class Exporter
       raise unless e.message.start_with? 'This is an aggregated project and issues should have been included'
     end
 
-    selected.each do |project, issue|
-      puts "\nProject #{project.name}"
-      puts issue.dump
+    if selected.empty?
+      file_system.log "No issues found to match #{keys.collect(&:inspect).join(', ')}"
+    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
     end
   end
 
@@ -116,7 +116,9 @@ class Exporter
 
   def jira_config filename = nil
     if filename
-      @jira_config = file_system.load_json(filename)
+      @jira_config = file_system.load_json(filename, fail_on_error: false)
+      raise "Unable to load Jira configuration file and cannot continue: #{filename.inspect}" if @jira_config.nil?
+
       @jira_config['url'] = $1 if @jira_config['url'] =~ /^(.+)\/+$/
     end
     @jira_config

data/lib/jirametrics/file_config.rb

@@ -66,15 +66,20 @@ class FileConfig
   # is that all empty values in the first column should be at the bottom.
   def sort_output all_lines
     all_lines.sort do |a, b|
+      result = nil
       if a[0] == b[0]
-        a[1..] <=> b[1..]
+        result = a[1..] <=> b[1..]
       elsif a[0].nil?
-        1
+        result = 1
       elsif b[0].nil?
-        -1
+        result = -1
       else
-        a[0] <=> b[0]
+        result = a[0] <=> b[0]
       end
+
+      # This will only happen if one of the objects isn't comparable. Seen in production.
+      result = -1 if result.nil?
+      result
     end
   end
 

data/lib/jirametrics/file_system.rb

@@ -35,6 +35,10 @@ class FileSystem
     log "Warning: #{message}", more: more, also_write_to_stderr: true
   end
 
+  def error message, more: nil
+    log "Error: #{message}", more: more, also_write_to_stderr: true
+  end
+
   def log message, more: nil, also_write_to_stderr: false
     message += " See #{logfile_name} for more details about this message." if more
 

data/lib/jirametrics/flow_efficiency_scatterplot.rb

@@ -27,7 +27,7 @@ class FlowEfficiencyScatterplot < ChartBase
           </mfrac>
         </math>
       </div>
-      <div style="background: yellow">Note that for this calculation to be accurate, we must be moving items into a
+      <div style="background: var(--warning-banner)">Note that for this calculation to be accurate, we must be moving items into a
         blocked or stalled state the moment we stop working on it, and most teams don't do that.
         So be aware that your team may have to change their behaviours if you want this chart to be useful.
       </div>

data/lib/jirametrics/html/aging_work_bar_chart.erb

@@ -38,22 +38,13 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
     plugins: {
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
 
           <% if percentage_line_x %>
           line: {
             type: 'line',
-            xMin: '<%= percentage_line_x %>',
-            xMax: '<%= percentage_line_x %>',
+            scaleID: 'x',
+            value: '<%= percentage_line_x %>',
             borderColor: <%= CssVariable.new('--aging-work-bar-chart-percentage-line-color').to_json %>,
             borderWidth: 1,
             drawTime: 'afterDraw'

data/lib/jirametrics/html/aging_work_in_progress_chart.erb

@@ -6,7 +6,7 @@ new Chart(document.getElementById(<%= chart_id.inspect %>).getContext('2d'),
 {
   type: 'bar',
   data: {
-    labels: [<%= column_headings.collect(&:inspect).join(',') %>],
+    labels: [<%= @board_columns.collect { |c| c.name.inspect }.join(',') %>],
     datasets: <%= JSON.generate(data_sets) %>
   },
   options: {
@@ -22,8 +22,10 @@ new Chart(document.getElementById(<%= chart_id.inspect %>).getContext('2d'),
           labelString: 'Date Completed'
         },
         grid: {
-          color: <%= CssVariable['--grid-line-color'].to_json %>
+          color: <%= CssVariable['--grid-line-color'].to_json %>,
+          z: 1 // draw the grid lines on top of the bars
         },
+        stacked: true
       },
       y: {
         scaleLabel: {
@@ -35,8 +37,11 @@ new Chart(document.getElementById(<%= chart_id.inspect %>).getContext('2d'),
           text: 'Age in days'
         },
         grid: {
-          color: <%= CssVariable['--grid-line-color'].to_json %>
+          color: <%= CssVariable['--grid-line-color'].to_json %>,
+          z: 1 // draw the grid lines on top of the bars
         },
+        stacked: true,
+        max: <%= (@max_age * 1.1).to_i %>
       }
     },
     plugins: {
@@ -44,14 +49,26 @@ new Chart(document.getElementById(<%= chart_id.inspect %>).getContext('2d'),
         callbacks: {
           label: function(context) {
             if( typeof(context.dataset.data[context.dataIndex]) == "number" ) {
-              return "85% of the issues, leave this column in "+context.dataset.data[context.dataIndex]+" days";
+              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";
             }
             else {
-              return context.dataset.data[context.dataIndex].title
+              return context.dataset.data[context.dataIndex].title;
             }
           }
         }
+      },
+      legend: {
+        labels: {
+          filter: function(item, chart) {
+            // Logic to remove a particular legend item goes here
+            return !item.text.includes('%');
+          }
+        }
       }
+
     }
   }
 });

data/lib/jirametrics/html/aging_work_table.erb

@@ -1,11 +1,12 @@
 <table class='standard'>
   <thead>
     <tr>
-      <th>Age (days)</th>
-      <th>E</th>
-      <th>B</th>
+      <th title="Age in days">Age</th>
+      <th title="Expedited">E</th>
+      <th title="Blocked / Stalled">B/S</th>
       <th>Issue</th>
       <th>Status</th>
+      <th>Forecast</th>
       <th>Fix versions</th>
       <% if any_scrum_boards %>
         <th>Sprints</th>
@@ -41,6 +42,7 @@
           <% end %>
         </td>
         <td><%= format_status issue.status, board: issue.board %></td>
+        <td><%= dates_text(issue) %></td>
         <td><%= fix_versions_text(issue) %></td>
         <% if any_scrum_boards %>
           <td><%= sprints_text(issue) %></td>

data/lib/jirametrics/html/cycletime_histogram.erb

@@ -1,6 +1,57 @@
 <div class="chart">
   <canvas id="<%= chart_id %>" width="<%= canvas_width %>" height="<%= canvas_height %>"></canvas>
 </div>
+<%
+if show_stats 
+  link_id = next_id
+  issues_id = next_id
+%>
+[<a id='<%= link_id %>' href="#" onclick='expand_collapse("<%= link_id %>", "<%= issues_id %>"); return false;'>Show details</a>]
+<div id="<%= issues_id %>" style="display: none;">
+  <div>
+     <table class="standard">
+      <tr>
+        <th>Issue Type</th>
+        <th>Min</th>
+        <th>Max</th>
+        <th>Avg</th>
+        <th>Mode</th>
+        <% percentiles.each do |p| %>
+           <th><%= p %>th</th>
+        <% end %>
+      </tr>
+      <% the_stats.each do |k, v| %>
+          <tr>
+            <td><%= k %></td>
+            <td style="text-align: right;"><%= v[:min] %></td>
+            <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>
+            <% end %>
+          </tr>
+       <% end %>
+     </table>
+  </div>
+  <div>
+    <p>These statistics help understand the <i>"shape"</i> of the cycletime histogram distribution, to help us with predictions.</p>
+    <ul>
+      <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 cycletime values are X or less. Typical percentiles of interest are:</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>
+      </ul>
+    </ul>
+  </div>
+</div>
+<%
+end
+%>
 <script>
 new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
 {
@@ -21,6 +72,8 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
         grid: {
           color: <%= CssVariable['--grid-line-color'].to_json %>
         },
+        min: 0,
+        offset: false, // Gets rid of the ugly padding on left.
       },
       y: {
         stacked: true,
@@ -34,6 +87,27 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
       }
     },
     plugins: {
+      annotation: {
+        annotations: {
+          <%
+            results = the_stats[:all][:percentiles]
+            results.each do |percentile, value|
+          %>
+          percentile<%= percentile.to_s %>: {
+            type: 'line',
+            scaleID: 'x',
+            value: <%= value %>,
+            borderWidth: 1,
+            drawTime: 'beforeDatasetsDraw',
+            label: {
+              enabled: true,
+              content: '<%= "#{percentile}%" %>',
+              position: 'start',
+            }
+          },
+          <% end %>
+        },
+      },
       tooltip: {
         callbacks: {
           label: function(context) {

data/lib/jirametrics/html/cycletime_scatterplot.erb

@@ -53,16 +53,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       autocolors: false,
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
 
           <% @percentage_lines.each_with_index do |args, index| %>
           <%   percent, color = args %>

data/lib/jirametrics/html/daily_wip_chart.erb

@@ -50,16 +50,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'),
       },
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       },
       legend: {

data/lib/jirametrics/html/expedited_chart.erb

@@ -55,16 +55,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       autocolors: false,
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html/index.css

@@ -2,6 +2,7 @@
   --body-background: white;
   --default-text-color: black;
   --grid-line-color: lightgray;
+  --warning-banner: yellow;
 
   --cycletime-scatterplot-overall-trendline-color: gray;
 
@@ -27,8 +28,16 @@
   --throughput_chart_total_line_color: gray;
   
   --aging-work-in-progress-chart-shading-color: lightgray;
+  --aging-work-in-progress-chart-shading-50-color: #2E8BC0; // green;
+  --aging-work-in-progress-chart-shading-85-color: #ADD8E6; // yellow;
+  --aging-work-in-progress-chart-shading-98-color: #FF8A8A; // orange;
+  --aging-work-in-progress-chart-shading-100-color: #FF2E2E; // red;
+  
   --aging-work-in-progress-by-age-trend-line-color: gray;
   
+  --aging-work-table-date-in-jeopardy: yellow;
+  --aging-work-table-date-overdue: red;
+
   --hierarchy-table-inactive-item-text-color: gray;
 
   --wip-chart-completed-color: #00ff00;
@@ -135,6 +144,8 @@ ul.quality_report {
 
 @media screen and (prefers-color-scheme: dark) {
   :root {
+    --warning-banner: #9F2B00;
+
     --non-working-days-color: #2f2f2f;
     --type-story-color: #6fb86f;
     --type-task-color: #0021b3;
@@ -150,8 +161,6 @@ ul.quality_report {
     --dead-color: black;
     --wip-chart-active-color: #2551c1;
 
-    --aging-work-in-progress-chart-shading-color: #b4b4b4;
-
     --status-category-inprogress-color: #1c49bb;
 
     --cycletime-scatterplot-overall-trendline-color: gray;

data/lib/jirametrics/html/index.erb

@@ -23,13 +23,20 @@
       window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
         location.reload()
       })
-
     </script>
     <style>
 <%= css %>
     </style>
+    <script type="text/javascript">
+      Chart.defaults.color = getComputedStyle(document.documentElement).getPropertyValue('--default-text-color');
+    </script>
   </head>
   <body>
+    <noscript>
+      <div style="padding: 1em; background: gray; color: white; font-size: 2em;">
+        Javascript is currently disabled and that means that almost all of the charts in this report won't render. If you'd loaded this from a folder on SharePoint then save it locally and load it again.
+      </div>
+    </noscript>
     <%= "\n" + @sections.collect { |text, type| text if type == :header }.compact.join("\n\n") %>
     <%= "\n" + @sections.collect { |text, type| text if type == :body }.compact.join("\n\n") %>
   </body>

data/lib/jirametrics/html/sprint_burndown.erb

@@ -56,16 +56,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       },
       annotation: {
         annotations: {
-          <% holidays().each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html/throughput_chart.erb

@@ -52,16 +52,7 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
       },
       annotation: {
         annotations: {
-          <% holidays.each_with_index do |range, index| %>
-          holiday<%= index %>: {
-            drawTime: 'beforeDraw',
-            type: 'box',
-            xMin: '<%= range.begin %>T00:00:00',
-            xMax: '<%= range.end %>T23:59:59',
-            backgroundColor: <%= CssVariable.new('--non-working-days-color').to_json %>,
-            borderColor: <%= CssVariable.new('--non-working-days-color').to_json %>
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/issue.rb

@@ -49,14 +49,26 @@ class Issue
 
   def summary = @raw['fields']['summary']
 
-  def status = Status.from_raw(@raw['fields']['status'])
-
   def labels = @raw['fields']['labels'] || []
 
   def author = @raw['fields']['creator']&.[]('displayName') || ''
 
   def resolution = @raw['fields']['resolution']&.[]('name')
 
+  def status
+    @status = Status.from_raw(@raw['fields']['status']) unless @status
+    @status
+  end
+
+  def status= status
+    @status = status
+  end
+
+  def due_date
+    text = @raw['fields']['duedate']
+    text.nil? ? nil : Date.parse(text)
+  end
+
   def url
     # Strangely, the URL isn't anywhere in the returned data so we have to fabricate it.
     "#{@board.server_url_prefix}/browse/#{key}"
@@ -129,13 +141,16 @@ class Issue
   end
 
   def most_recent_status_change
-    # We artificially insert a status change to represent creation so by definition there will always be at least one.
-    changes.reverse.find { |change| change.status? }
+    # Any issue that we loaded from its own file will always have a status as we artificially insert a status
+    # change to represent creation. Issues that were just fragments referenced from a main issue (ie a linked issue)
+    # may not have any status changes as we have no idea when it was created. This will be nil in that case
+    status_changes.last
   end
 
   # Are we currently in this status? If yes, then return the most recent status change.
   def currently_in_status *status_names
     change = most_recent_status_change
+    return false if change.nil?
 
     change if change.current_status_matches(*status_names)
   end
@@ -145,6 +160,7 @@ class Issue
     category_ids = find_status_category_ids_by_names category_names
 
     change = most_recent_status_change
+    return false if change.nil?
 
     status = find_or_create_status id: change.value_id, name: change.value
     change if status && category_ids.include?(status.category.id)
@@ -604,12 +620,17 @@ class Issue
     end
 
     (changes + (@discarded_changes || [])).each do |change|
-      value = change.value
-      old_value = change.old_value
+      if change.status?
+        value = "#{change.value.inspect}:#{change.value_id.inspect}"
+        old_value = change.old_value ? "#{change.old_value.inspect}:#{change.old_value_id.inspect}" : nil
+      else
+        value = compact_text(change.value).inspect
+        old_value = change.old_value ? compact_text(change.old_value).inspect : nil
+      end
 
       message = +''
-      message << "#{compact_text(old_value).inspect} -> " unless old_value.nil? || old_value.empty?
-      message << compact_text(value).inspect
+      message << "#{old_value} -> " unless old_value.nil? || old_value.empty?
+      message << value
       if change.artificial?
         message << ' (Artificial entry)' if change.artificial?
       else

data/lib/jirametrics/jira_gateway.rb

@@ -14,9 +14,15 @@ class JiraGateway
   def call_url relative_url:
     command = make_curl_command url: "#{@jira_url}#{relative_url}"
     result = call_command command
-    JSON.parse result
-  rescue => e # rubocop:disable Style/RescueStandardError
-    raise "Error #{e.message.inspect} when parsing result: #{result.inspect}"
+    begin
+      json = JSON.parse(result)
+    rescue # rubocop:disable Style/RescueStandardError
+      raise "Error when parsing result: #{result.inspect}"
+    end
+
+    raise "Download failed with: #{JSON.pretty_generate(json)}" unless json_successful?(json)
+
+    json
   end
 
   def call_command command
@@ -61,4 +67,11 @@ class JiraGateway
     command << " --url \"#{url}\""
     command
   end
+
+  def json_successful? json
+    return false if json.is_a?(Hash) && (json['error'] || json['errorMessages'] || json['errorMessage'])
+    return false if json.is_a?(Array) && json.first == 'errorMessage'
+
+    true
+  end
 end

data/lib/jirametrics/project_config.rb

@@ -106,7 +106,7 @@ class ProjectConfig
 
   def board id:, &block
     config = BoardConfig.new(id: id, block: block, project_config: self)
-    config.run
+    config.run if data_downloaded?
     @board_configs << config
   end
 

data/lib/jirametrics/status.rb

@@ -36,13 +36,10 @@ class Status
   end
 
   def self.from_raw raw
-    category_config = raw['statusCategory']
+    raise "raw cannot be nil" if raw.nil?
 
-    legal_keys = %w[new indeterminate done]
-    unless legal_keys.include? category_config['key']
-      puts "Category key #{category_config['key'].inspect} should be one of #{legal_keys.inspect}. Found:\n" \
-        "#{category_config}"
-    end
+    category_config = raw['statusCategory']
+    raise "statusCategory can't be nil in #{category_config.inspect}" if category_config.nil?
 
     Status.new(
       name: raw['name'],