jirametrics 2.0 → 2.11

data/lib/jirametrics/html/index.css

@@ -0,0 +1,209 @@
+:root {
+  --body-background: white;
+  --default-text-color: black;
+  --grid-line-color: lightgray;
+  --warning-banner: yellow;
+
+  --cycletime-scatterplot-overall-trendline-color: gray;
+
+  --non-working-days-color: #F0F0F0;
+  --expedited-color: red;
+  --blocked-color: #FF7400;
+  --stalled-color: orange;
+  --dead-color: black;
+
+  --type-story-color: #4bc14b;
+  --type-task-color: blue;
+  --type-bug-color: orange;
+  --type-spike-color: #9400D3;
+
+  --status-category-todo-color: gray;
+  --status-category-inprogress-color: #2663ff;
+  --status-category-done-color: #00ff00;
+  --status-category-unknown-color: black;
+
+  --aging-work-bar-chart-percentage-line-color: red;
+  --aging-work-bar-chart-separator-color: white;
+
+  --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;
+  --wip-chart-completed-but-not-started-color: #99FF99;
+  --wip-chart-duration-less-than-day-color: #ffef41;
+  --wip-chart-duration-week-or-less-color: #dcc900;
+  --wip-chart-duration-two-weeks-or-less-color: #dfa000;
+  --wip-chart-duration-four-weeks-or-less-color: #eb7200;
+  --wip-chart-duration-more-than-four-weeks-color: #e70000;
+  --wip-chart-active-color: #326cff;
+  --wip-chart-border-color: gray;
+
+  --estimate-accuracy-chart-completed-fill-color: #00ff00;
+  --estimate-accuracy-chart-completed-border-color: green;
+  --estimate-accuracy-chart-active-fill-color: #FFCCCB;
+  --estimate-accuracy-chart-active-border-color: red;
+
+  --expedited-chart-no-longer-expedited: gray;
+  --expedited-chart-dot-issue-started-color: orange;
+  --expedited-chart-dot-issue-stopped-color: green;
+  --expedited-chart-dot-expedite-started-color: red;
+  --expedited-chart-dot-expedite-stopped-color: green;
+
+  --sprint-burndown-sprint-color-1: blue;
+  --sprint-burndown-sprint-color-2: orange;
+  --sprint-burndown-sprint-color-3: green;
+  --sprint-burndown-sprint-color-4: red;
+  --sprint-burndown-sprint-color-5: brown;
+
+
+}
+
+body {
+  background-color: var(--body-background);
+  color: var(--default-text-color);
+}
+
+h1 {
+  border: 1px solid black;
+  background: lightgray;
+  padding-left: 0.2em;
+}
+dl, dd, dt {
+  padding: 0;
+  margin: 0;
+}
+dd {
+  margin-bottom:  0.4em;
+}
+span.highlight {
+  background: #FDD5B1;
+}
+a.issue_key {
+  white-space: nowrap;
+}
+table.standard {
+  th {
+    border-bottom: 1px solid gray;
+    position: sticky;
+    top: 0;
+    background: white;
+  }
+  td {
+    padding-left: 0.5em;
+    padding-right: 0.5em;
+    vertical-align: top;
+  }
+  tr:nth-child(odd){
+    background-color: #eee;
+  }
+}
+
+.chart {
+  background-color: white;
+}
+
+div.p {
+  margin: 0.5em 0;
+  padding: 0;
+}
+
+div.color_block {
+  display: inline-block;
+  width: 0.9em;
+  height: 0.9em;
+  border: 1px solid black;
+}
+
+ul.quality_report {
+  list-style-type: '⮕';
+  ::marker {
+    color: red;
+  }
+  li {
+    padding: 0.2em;
+  }
+}
+
+#footer {
+  text-align: center;
+  margin-top: 1em;
+  border-top: 1px solid gray;
+}
+
+@media screen and (prefers-color-scheme: dark) {
+  :root {
+    --warning-banner: #9F2B00;
+
+    --non-working-days-color: #2f2f2f;
+    --type-story-color: #6fb86f;
+    --type-task-color: #0021b3;
+    --type-bug-color: #bb5603;
+
+    --body-background: #343434;
+    --default-text-color: #aaa;
+    --grid-line-color: #424242;
+
+    --expedited-color: #b90000;
+    --blocked-color: #c75b02;
+    --stalled-color: #ae7202;
+    --dead-color: black;
+    --wip-chart-active-color: #2551c1;
+
+    --status-category-inprogress-color: #1c49bb;
+
+    --cycletime-scatterplot-overall-trendline-color: gray;
+
+    --hierarchy-table-inactive-item-text-color: #939393;
+
+    --wip-chart-completed-color: #03cb03;
+    --wip-chart-completed-but-not-started-color: #99FF99;
+    --wip-chart-duration-less-than-day-color: #d2d988;
+    --wip-chart-duration-week-or-less-color: #dfcd00;
+    --wip-chart-duration-two-weeks-or-less-color: #cf9400;
+    --wip-chart-duration-four-weeks-or-less-color: #c25e00;
+    --wip-chart-duration-more-than-four-weeks-color: #8e0000;
+  }
+
+  h1 {
+    color: #e0e0e0;
+    background-color: #656565;
+  }
+
+  a[href] {
+    color: #1e8ad6;
+  }
+
+  a[href]:hover {
+    color: #3ba0e6;
+  }
+
+  .chart {
+    background: var(--body-background);
+  }
+
+  table.standard {
+    th {
+      border-bottom: 1px solid gray;
+      background: var(--body-background);
+    }
+    tr:nth-child(odd){
+      background-color: #656565;
+    }
+  }
+
+  div.color_block {
+    border: 1px solid lightgray;
+  }
+}

data/lib/jirametrics/html/index.erb

@@ -1,6 +1,7 @@
 <html>
   <head>
     <meta charset="UTF-8">
+    <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>
     <script src="https://cdn.jsdelivr.net/npm/chartjs-adapter-moment@^1"></script>
@@ -17,49 +18,25 @@
           document.getElementById(issues_id).style.display = 'none'
         }
       }
+      // If we switch between light/dark mode then force a refresh so all charts will redraw correctly
+      // in the other colour scheme.
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
+        location.reload()
+      })
     </script>
     <style>
-      h1 {
-        border: 1px solid black;
-        background: lightgray;
-        padding-left: 0.2em;
-      }
-      dl, dd, dt {
-        padding: 0;
-        margin: 0;
-      }
-      dd {
-        margin-bottom:  0.4em;
-      }
-      span.highlight {
-        background: #FDD5B1;
-      }
-      a.issue_key {
-        white-space: nowrap;
-      }
-      table.standard thead tr th {
-        border-bottom: 1px solid gray;
-        position: sticky;
-        top: 0;
-        background: white;
-      }
-      table.standard tbody tr td {
-        padding-left: 0.5em;
-        padding-right: 0.5em;
-        vertical-align: top;
-      }
-      table.standard tbody tr:nth-child(odd){
-        background-color: #eee;
-      }
-      .quality_note_bullet {
-        color: red;
-      }
-      </style>
+<%= css %>
+    </style>
+    <script type="text/javascript">
+      Chart.defaults.color = getComputedStyle(document.documentElement).getPropertyValue('--default-text-color');
+    </script>
   </head>
   <body>
-    <div>
-      Page generated <%= (timezone_offset.nil? ? DateTime.now : DateTime.now.new_offset(timezone_offset)).strftime('%Y-%b-%d at %I:%M:%S%P') %>
-    </div>
+    <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

@@ -1,6 +1,6 @@
 <h2>Burndown by <%= y_axis_title %></h2>
 
-<div>
+<div class="chart">
   <canvas id="<%= chart_id %>" width="<%= canvas_width %>" height="<%= canvas_height %>"></canvas>
 </div>
 <script>
@@ -26,8 +26,10 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           labelString: 'Date'
         },
         min: "<%= date_range.begin.to_s %>",
-        max: "<%= (date_range.end + 1).to_s %>"
-
+        max: "<%= (date_range.end + 1).to_s %>",
+        grid: {
+          color: <%= CssVariable['--grid-line-color'].to_json %>
+        },
       },
       y: {
         scaleLabel: {
@@ -38,7 +40,10 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           display: true,
           text: "<%= y_axis_title %>"
         },
-        min: 0.0
+        min: 0.0,
+        grid: {
+          color: <%= CssVariable['--grid-line-color'].to_json %>
+        },
       }
     },
     plugins: {
@@ -51,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: '#F0F0F0',
-            borderColor: '#F0F0F0'
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html/throughput_chart.erb

@@ -1,5 +1,5 @@
 
-<div>
+<div class="chart">
   <canvas id="<%= chart_id %>" width="<%= canvas_width %>" height="<%= canvas_height %>"></canvas>
 </div>
 <script>
@@ -23,7 +23,10 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
         scaleLabel: {
           display: true,
           labelString: 'Date Completed'
-        }
+        },
+        grid: {
+          color: <%= CssVariable['--grid-line-color'].to_json %>
+        },
       },
       y: {
         scaleLabel: {
@@ -33,7 +36,10 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
           display: true,
           text: 'Count of items'
         },
-        min: 0
+        min: 0,
+        grid: {
+          color: <%= CssVariable['--grid-line-color'].to_json %>
+        },
       },
     },
     plugins: {
@@ -46,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: '#F0F0F0',
-            borderColor: '#F0F0F0'
-          },
-          <% end %>
+          <%= working_days_annotation %>
         }
       }
     }

data/lib/jirametrics/html_report_config.rb

@@ -5,45 +5,104 @@ require 'jirametrics/self_or_issue_dispatcher'
 
 class HtmlReportConfig
   include SelfOrIssueDispatcher
-  include DiscardChangesBefore
 
-  attr_reader :file_config, :sections
+  attr_reader :file_config, :sections, :charts
+
+  def self.define_chart name:, classname:, deprecated_warning: nil, deprecated_date: nil
+    lines = []
+    lines << "def #{name} &block"
+    lines << '  block = ->(_) {} unless block'
+    if deprecated_warning
+      lines << "  file_system.deprecated date: #{deprecated_date.inspect}, message: #{deprecated_warning.inspect}"
+    end
+    lines << "  execute_chart #{classname}.new(block)"
+    lines << 'end'
+    module_eval lines.join("\n"), __FILE__, __LINE__
+  end
+
+  define_chart name: 'aging_work_bar_chart', classname: 'AgingWorkBarChart'
+  define_chart name: 'aging_work_table', classname: 'AgingWorkTable'
+  define_chart name: 'cycletime_scatterplot', classname: 'CycletimeScatterplot'
+  define_chart name: 'daily_wip_chart', classname: 'DailyWipChart'
+  define_chart name: 'daily_wip_by_age_chart', classname: 'DailyWipByAgeChart'
+  define_chart name: 'daily_wip_by_blocked_stalled_chart', classname: 'DailyWipByBlockedStalledChart'
+  define_chart name: 'daily_wip_by_parent_chart', classname: 'DailyWipByParentChart'
+  define_chart name: 'throughput_chart', classname: 'ThroughputChart'
+  define_chart name: 'expedited_chart', classname: 'ExpeditedChart'
+  define_chart name: 'cycletime_histogram', classname: 'CycletimeHistogram'
+  define_chart name: 'estimate_accuracy_chart', classname: 'EstimateAccuracyChart'
+  define_chart name: 'hierarchy_table', classname: 'HierarchyTable'
+  define_chart name: 'flow_efficiency_scatterplot', classname: 'FlowEfficiencyScatterplot'
+
+  define_chart name: 'daily_wip_by_type', classname: 'DailyWipChart',
+    deprecated_warning: 'This is the same as daily_wip_chart. Please use that one', deprecated_date: '2024-05-23'
+  define_chart name: 'story_point_accuracy_chart', classname: 'EstimateAccuracyChart',
+    deprecated_warning: 'Renamed to estimate_accuracy_chart. Please use that one', deprecated_date: '2024-05-23'
 
   def initialize file_config:, block:
     @file_config = file_config
     @block = block
-    # @cycletimes = []
-    @sections = []
+    @sections = [] # Where we store the chunks of text that will be assembled into the HTML
+    @charts = [] # Where we store all the charts we executed so we can assert against them.
   end
 
   def cycletime label = nil, &block
-    # TODO: This is about to become deprecated
-
     @file_config.project_config.all_boards.each_value do |board|
-      raise 'Multiple cycletimes not supported yet' if board.cycletime
+      raise 'Multiple cycletimes not supported' if board.cycletime
 
-      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
+      board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block, file_system: file_system)
     end
   end
 
+  # Mostly this is its own method so it can be called from the config
+  def included_projects
+    @file_config.project_config.aggregate_config.included_projects
+  end
+
   def run
     instance_eval(&@block)
 
     # The quality report has to be generated last because otherwise cycletime won't have been
     # set. Then we have to rotate it to the first position so it's at the top of the report.
-    execute_chart DataQualityReport.new(@original_issue_times || {})
+    execute_chart DataQualityReport.new(file_config.project_config.discarded_changes_data)
     @sections.rotate!(-1)
 
-    File.open @file_config.output_filename, 'w' do |file|
-      html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
-      erb = ERB.new File.read("#{html_directory}/index.erb")
-      file.puts erb.result(binding)
+    html create_footer
+
+    html_directory = "#{Pathname.new(File.realpath(__FILE__)).dirname}/html"
+    css = load_css html_directory: html_directory
+    erb = ERB.new file_system.load(File.join(html_directory, 'index.erb'))
+    file_system.save_file content: erb.result(binding), filename: @file_config.output_filename
+  end
+
+  def file_system
+    @file_config.project_config.exporter.file_system
+  end
+
+  def log message
+    file_system.log message
+  end
+
+  def load_css html_directory:
+    base_css_filename = File.join(html_directory, 'index.css')
+    base_css = file_system.load(base_css_filename)
+    log("Loaded CSS:  #{base_css_filename}")
+
+    extra_css_filename = settings['include_css']
+    if extra_css_filename
+      if File.exist?(extra_css_filename)
+        base_css << "\n\n" << file_system.load(extra_css_filename)
+        log("Loaded CSS:  #{extra_css_filename}")
+      else
+        log("Unable to find specified CSS file: #{extra_css_filename}")
+      end
     end
+
+    base_css
   end
 
-  def board_id id = nil
-    @board_id = id unless id.nil?
-    @board_id
+  def board_id id
+    @board_id = id
   end
 
   def timezone_offset
@@ -51,6 +110,8 @@ class HtmlReportConfig
   end
 
   def aging_work_in_progress_chart board_id: nil, &block
+    block ||= ->(_) {}
+
     if board_id.nil?
       ids = issues.collect { |i| i.board.id }.uniq.sort
     else
@@ -64,52 +125,13 @@ class HtmlReportConfig
     end
   end
 
-  def aging_work_bar_chart &block
-    execute_chart AgingWorkBarChart.new(block)
-  end
-
-  def aging_work_table &block
-    execute_chart AgingWorkTable.new(block)
-  end
-
-  def cycletime_scatterplot &block
-    execute_chart CycletimeScatterplot.new block
-  end
-
-  def daily_wip_chart &block
-    execute_chart DailyWipChart.new(block)
-  end
-
-  def daily_wip_by_age_chart &block
-    execute_chart DailyWipByAgeChart.new block
-  end
-
-  def daily_wip_by_type &block
-    execute_chart DailyWipChart.new block
-  end
-
-  def daily_wip_by_blocked_stalled_chart
-    execute_chart DailyWipByBlockedStalledChart.new
-  end
-
-  def throughput_chart &block
-    execute_chart ThroughputChart.new(block)
-  end
-
-  def expedited_chart
-    execute_chart ExpeditedChart.new
-  end
-
-  def cycletime_histogram &block
-    execute_chart CycletimeHistogram.new block
-  end
-
   def random_color
     "##{Random.bytes(3).unpack1('H*')}"
   end
 
   def html string, type: :body
-    raise "Unexpected type: #{type}" unless %i[body header].include? type
+    allowed_types = %i[body header]
+    raise "Unexpected type: #{type} allowed_types: #{allowed_types.inspect}" unless allowed_types.include? type
 
     @sections << [string, type]
   end
@@ -120,41 +142,26 @@ class HtmlReportConfig
     end
   end
 
-  def story_point_accuracy_chart &block
-    execute_chart StoryPointAccuracyChart.new block
-  end
-
-  def hierarchy_table &block
-    execute_chart HierarchyTable.new block
-  end
-
-  def discard_changes_before_hook issues_cutoff_times
-    # raise 'Cycletime must be defined before using discard_changes_before' unless @cycletime
-
-    @original_issue_times = {}
-    issues_cutoff_times.each do |issue, cutoff_time|
-      started = issue.board.cycletime.started_time(issue)
-      if started && started <= cutoff_time
-        # We only need to log this if data was discarded
-        @original_issue_times[issue] = { cutoff_time: cutoff_time, started_time: started }
-      end
-    end
-  end
-
   def dependency_chart &block
     execute_chart DependencyChart.new block
   end
 
+  # have an explicit method here so that index.erb can call 'settings' just as any other erb can.
+  def settings
+    @file_config.project_config.settings
+  end
+
   def execute_chart chart, &after_init_block
     project_config = @file_config.project_config
 
+    chart.file_system = file_system
     chart.issues = issues
     chart.time_range = project_config.time_range
     chart.timezone_offset = timezone_offset
-    chart.settings = project_config.settings
+    chart.settings = settings
 
     chart.all_boards = project_config.all_boards
-    chart.board_id = find_board_id if chart.respond_to? :board_id=
+    chart.board_id = find_board_id
     chart.holiday_dates = project_config.exporter.holiday_dates
 
     time_range = @file_config.project_config.time_range
@@ -163,6 +170,7 @@ class HtmlReportConfig
 
     after_init_block&.call chart
 
+    @charts << chart
     html chart.run
   end
 
@@ -174,19 +182,33 @@ class HtmlReportConfig
     @file_config.issues
   end
 
+  # For use by the user config
   def find_board id
     @file_config.project_config.all_boards[id]
   end
 
-  def project_name
-    @file_config.project_config.name
-  end
-
+  # For use by the user config
   def boards
     @file_config.project_config.board_configs.collect(&:id).collect { |id| find_board id }
   end
 
-  def find_project_by_name name
-    @file_config.project_config.exporter.project_configs.find { |p| p.name == name }
+  def create_footer now: DateTime.now
+    now = now.new_offset(timezone_offset)
+    version = Gem.loaded_specs['jirametrics']&.version || 'Next'
+
+    <<~HTML
+      <section id="footer">
+        Report generated on <b>#{now.strftime('%Y-%b-%d')}</b> at <b>#{now.strftime('%I:%M:%S%P %Z')}</b>
+        with <a href="https://jirametrics.org">JiraMetrics</a> <b>v#{version}</b>
+      </section>
+    HTML
+  end
+
+  def discard_changes_before status_becomes: nil, &block
+    file_system.deprecated(
+      date: '2025-01-09',
+      message: 'discard_changes_before is now only supported at the project level'
+    )
+    file_config.project_config.discard_changes_before status_becomes: status_becomes, &block
   end
 end