jirametrics 1.5 → 2.0

data/lib/jirametrics/examples/aggregated_project.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 # This file is really intended to give you ideas about how you might configure your own reports, not
-# as a complete setup that will work in every case. 
+# as a complete setup that will work in every case.
 #
-# See https://github.com/mikebowler/jirametrics/wiki/Examples-folder for moreclass Exporter
+# See https://github.com/mikebowler/jirametrics/wiki/Examples-folder for more details
+#
+# The point of an AGGREGATED report is that we're now looking at a higher level. We might use this in a
+# S2 meeting (Scrum of Scrums) to talk about the things that are happening across teams, not within a
+# single team. For that reason, we look at slightly different things that we would on a single team board.
+
 class Exporter
   def aggregated_project name:, project_names:
     project name: name do
@@ -29,10 +34,63 @@ class Exporter
               rules.label = issue.board.name
             end
           end
-          aging_work_in_progress_chart
+          # aging_work_in_progress_chart
+          daily_wip_chart do
+            header_text 'Daily WIP by Parent'
+            description_text <<-TEXT
+              <p>How much work is in progress, grouped by the parent of the issue. This will give us an
+              indication of how focused we are on higher level objectives. If there are many parent
+              tickets in progress at the same time, either this team has their focus scattered or we
+              aren't doing a good job of
+              <a href="https://improvingflow.com/2024/02/21/slicing-epics.html">splitting those parent
+              tickets</a>. Neither of those is desirable.</p>
+              <p>If you're expecting all work items to have parents and there are a lot that don't,
+              that's also something to look at. Consider whether there is even value in aggregating
+              these projects if they don't share parent dependencies. Aggregation helps us when we're
+              looking at related work and if there aren't parent dependencies then the work may not
+              be related.</p>
+            TEXT
+            grouping_rules do |issue, rules|
+              rules.label = issue.parent&.key || 'No parent'
+              rules.color = 'white' if rules.label == 'No parent'
+            end
+          end
           aging_work_table do
+            # In an aggregated report, we likely only care about items that are old so exclude anything
+            # under 21 days.
             age_cutoff 21
           end
+
+          dependency_chart do
+            header_text 'Dependencies across boards'
+            description_text 'We are only showing dependencies across boards.'
+
+            # By default, the issue doesn't show what board it's on and this is important for an
+            # aggregated view
+            issue_rules do |issue, rules|
+              key = issue.key
+              key = "<S>#{key} </S> " if issue.status.category_name == 'Done'
+              rules.label = "<#{key} [#{issue.type}]<BR/>#{issue.board.name}<BR/>#{word_wrap issue.summary}>"
+            end
+
+            link_rules do |link, rules|
+              # By default, the dependency chart shows everything. Clean it up a bit.
+              case link.name
+              when 'Cloners'
+                # We don't want to see any clone links at all.
+                rules.ignore
+              when 'Blocks'
+                # For blocks, by default Jira will have links going both
+                # ways and we want them only going one way. Also make the
+                # link red.
+                rules.merge_bidirectional keep: 'outward'
+                rules.line_color = 'red'
+              end
+
+              # Because this is the aggregated view, let's hide any link that doesn't cross boards.
+              rules.ignore if link.origin.board == link.other_issue.board
+            end
+          end
         end
       end
     end

data/lib/jirametrics/examples/standard_project.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is really intended to give you ideas about how you might configure your own reports, not
-# as a complete setup that will work in every case. 
+# as a complete setup that will work in every case.
 #
 # See https://github.com/mikebowler/jirametrics/wiki/Examples-folder for more
 class Exporter
@@ -83,13 +83,13 @@ class Exporter
               How much work is in progress, grouped by the parent of the issue. This will give us an
               indication of how focused we are on higher level objectives. If there are many parent
               tickets in progress at the same time, either this team has their focus scattered or we
-              aren't doing a good job of 
+              aren't doing a good job of
               <a href="https://improvingflow.com/2024/02/21/slicing-epics.html">splitting those parent
               tickets</a>. Neither of those is desirable.
             TEXT
             grouping_rules do |issue, rules|
               rules.label = issue.parent&.key || 'No parent'
-              rules.color = 'white' if rules.label == 'No parent' 
+              rules.color = 'white' if rules.label == 'No parent'
             end
           end
           expedited_chart

data/lib/jirametrics/expedited_chart.rb

@@ -39,9 +39,9 @@ class ExpeditedChart < ChartBase
   end
 
   def run
-    data_sets = find_expedited_issues.collect do |issue|
+    data_sets = find_expedited_issues.filter_map do |issue|
       make_expedite_lines_data_set(issue: issue, expedite_data: prepare_expedite_data(issue))
-    end.compact
+    end
 
     if data_sets.empty?
       '<h1>Expedited work</h1>There is no expedited work in this time period.'
@@ -84,7 +84,7 @@ class ExpeditedChart < ChartBase
       prepare_expedite_data(issue).empty?
     end
 
-    expedited_issues.sort { |a, b| a.key_as_i <=> b.key_as_i }
+    expedited_issues.sort_by(&:key_as_i)
   end
 
   def later_date date1, date2
@@ -110,7 +110,7 @@ class ExpeditedChart < ChartBase
 
     expedite_data << [started_time, :issue_started] if started_time
     expedite_data << [stopped_time, :issue_stopped] if stopped_time
-    expedite_data.sort! { |a, b| a[0] <=> b[0] }
+    expedite_data.sort_by! { |a| a[0] }
 
     # If none of the data would be visible on the chart then skip it.
     return nil unless expedite_data.any? { |time, _action| time.to_date >= date_range.begin }

data/lib/jirametrics/experimental/generator.rb

@@ -38,7 +38,7 @@ class FakeIssue
         priority: {
           name: ''
         },
-        summary: RandomWord.phrases.next.gsub(/_/, ' '),
+        summary: RandomWord.phrases.next.gsub(_, ' '),
         issuelinks: [],
         fixVersions: []
       }
@@ -137,7 +137,7 @@ class Generator
     remove_old_files
     @date_range.each_with_index do |date, day|
       yield date, day if block_given?
-      process_date(date, day) if (1..5).include? date.wday # Weekday
+      process_date(date, day) if (1..5).cover? date.wday # Weekday
     end
 
     @issues.each do |issue|
@@ -158,7 +158,7 @@ class Generator
   def remove_old_files
     path = "#{@target_path}#{@file_prefix}_issues"
     Dir.foreach path do |file|
-      next unless file =~ /-\d+\.json$/
+      next unless file.match?(/-\d+\.json$/)
 
       filename = "#{path}/#{file}"
       File.unlink filename
@@ -191,8 +191,9 @@ class Generator
       end
     end
 
+    possible_capacities = [0, 1, 1, 1, 2]
     @workers.each do |worker|
-      worker_capacity = [0, 1, 1, 1, 2].sample
+      worker_capacity = possible_capacities.sample
       if worker.issue.nil? || worker.issue.done?
         type = lucky?(89) ? 'Story' : 'Bug'
         worker.issue = next_issue_for worker: worker, date: date, type: type

data/lib/jirametrics/experimental/info.rb

@@ -13,7 +13,7 @@ class InfoDumper
       path = "#{@target_dir}#{prefix}_issues/#{key}.json"
       path = "#{@target_dir}#{prefix}_issues"
       Dir.foreach path do |file|
-        if file =~ /^#{key}.+\.json$/
+        if file.match?(/^#{key}.+\.json$/)
           issue = Issue.new raw: JSON.parse(File.read(File.join(path, file))), board: nil
           dump issue
         end
@@ -74,4 +74,4 @@ if __FILE__ == $PROGRAM_NAME
   ARGV.each do |key|
     InfoDumper.new.run key
   end
-end
+end

data/lib/jirametrics/exporter.rb

@@ -3,37 +3,17 @@
 require 'fileutils'
 
 class Object
-  def deprecated message:, date: nil
-    text = String.new
-    text << 'Deprecated'
-    text << "(#{date})"
-    text << ': '
+  def deprecated message:
+    text = +''
+    text << 'Deprecated:'
     text << message
-    text << "\n-> Called from #{caller[0]}"
-    warn text
-  end
-
-  def assert_jira_behaviour_true condition, &block
-    block.call if ENV['RACK_ENV'] == 'test' # Always expand the block if we're running in a test
-    failed_jira_behaviour(block) unless condition
-  end
-
-  def assert_jira_behaviour_false condition, &block
-    block.call if ENV['RACK_ENV'] == 'test' # Always expand the block if we're running in a test
-    failed_jira_behaviour(block) if condition
-  end
-
-  def failed_jira_behaviour block
-    text = String.new
-    text << 'Jira not doing what we expected. Results may be incorrect: '
-    text << block.call
-    text << "\n-> Called from #{caller[1]}"
+    text << "\n-> Called from #{caller(1..1).first}"
     warn text
   end
 end
 
 class Exporter
-  attr_reader :project_configs
+  attr_reader :project_configs, :file_system
 
   def self.configure &block
     exporter = Exporter.new
@@ -43,12 +23,13 @@ class Exporter
 
   def self.instance = @@instance
 
-  def initialize
+  def initialize file_system: FileSystem.new
     @project_configs = []
     @timezone_offset = '+00:00'
     @target_path = '.'
     @holiday_dates = []
     @downloading = false
+    @file_system = file_system
   end
 
   def export name_filter:
@@ -62,14 +43,19 @@ class Exporter
     @downloading = true
     logfile_name = 'downloader.log'
     File.open logfile_name, 'w' do |logfile|
+      file_system.logfile = logfile
+      file_system.logfile_name = logfile_name
+
       each_project_config(name_filter: name_filter) do |project|
         project.evaluate_next_level
         next if project.aggregated_project?
 
         project.download_config.run
-        downloader = Downloader.new(download_config: project.download_config)
-        downloader.logfile = logfile
-        downloader.logfile_name = logfile_name
+        downloader = Downloader.new(
+          download_config: project.download_config,
+          file_system: file_system,
+          jira_gateway: JiraGateway.new(file_system: file_system)
+        )
         downloader.run
       end
     end
@@ -107,7 +93,7 @@ class Exporter
   end
 
   def jira_config filename = nil
-    @jira_config = JsonFileLoader.new.load(filename) unless filename.nil?
+    @jira_config = file_system.load_json(filename) unless filename.nil?
     @jira_config
   end
 

data/lib/jirametrics/file_system.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'json'
+
+class FileSystem
+  attr_accessor :logfile, :logfile_name
+
+  def load_json filename, fail_on_error: true
+    return nil if fail_on_error == false && File.exist?(filename) == false
+
+    JSON.parse File.read(filename)
+  end
+
+  def save_json json:, filename:
+    file_path = File.dirname(filename)
+    FileUtils.mkdir_p file_path unless File.exist?(file_path)
+
+    File.write(filename, JSON.pretty_generate(compress json))
+  end
+
+  def log message
+    logfile.puts message
+  end
+
+  # In some Jira instances, a sizeable portion of the JSON is made up of empty fields. I've seen
+  # cases where this simple compression will drop the filesize by half.
+  def compress node
+    if node.is_a? Hash
+      node.reject! { |_key, value| value.nil? || (value.is_a?(Array) && value.empty?) }
+      node.each_value { |value| compress value }
+    elsif node.is_a? Array
+      node.each { |a| compress a }
+    end
+    node
+  end
+end

data/lib/jirametrics/groupable_issue_chart.rb

@@ -5,15 +5,6 @@ require 'jirametrics/grouping_rules'
 
 module GroupableIssueChart
   def init_configuration_block user_provided_block, &default_block
-    # The user provided a block but it's using the old deprecated style
-    if user_provided_block && user_provided_block.arity == 1
-      deprecated date: '2022-10-02', message: "#{self.class}: Use the new grouping_rules syntax"
-      grouping_rules do |issue, rules|
-        rules.label, rules.color = user_provided_block.call(issue)
-      end
-      return
-    end
-
     if user_provided_block
       instance_eval(&user_provided_block)
       return if @group_by_block

data/lib/jirametrics/hierarchy_table.rb

@@ -17,7 +17,7 @@ class HierarchyTable < ChartBase
   def run
     tree_organizer = TreeOrganizer.new issues: @issues
     unless tree_organizer.cyclical_links.empty?
-      message = String.new
+      message = +''
       message << '<p>Found cyclical links in the parent hierarchy. This is an error and should be '
       message << 'fixed.</p><ul>'
       tree_organizer.cyclical_links.each do |link|

data/lib/jirametrics/html_report_config.rb

@@ -19,7 +19,7 @@ class HtmlReportConfig
   def cycletime label = nil, &block
     # TODO: This is about to become deprecated
 
-    @file_config.project_config.all_boards.each do |_id, board|
+    @file_config.project_config.all_boards.each_value do |board|
       raise 'Multiple cycletimes not supported yet' if board.cycletime
 
       board.cycletime = CycleTimeConfig.new(parent_config: self, label: label, block: block)
@@ -68,12 +68,7 @@ class HtmlReportConfig
     execute_chart AgingWorkBarChart.new(block)
   end
 
-  def aging_work_table priority_name = nil, &block
-    if priority_name
-      deprecated message: 'priority name should no longer be passed into the chart. Specify it in the ' \
-        'board declaration. See https://github.com/mikebowler/jira-export/wiki/Deprecated',
-        date: '2022-12-26'
-    end
+  def aging_work_table &block
     execute_chart AgingWorkTable.new(block)
   end
 
@@ -81,11 +76,6 @@ class HtmlReportConfig
     execute_chart CycletimeScatterplot.new block
   end
 
-  def total_wip_over_time_chart &block
-    puts 'Deprecated(total_wip_over_time_chart). Use daily_wip_by_age_chart instead.'
-    execute_chart DailyWipByAgeChart.new block
-  end
-
   def daily_wip_chart &block
     execute_chart DailyWipChart.new(block)
   end
@@ -106,17 +96,7 @@ class HtmlReportConfig
     execute_chart ThroughputChart.new(block)
   end
 
-  def blocked_stalled_chart
-    puts 'Deprecated(blocked_stalled_chart). Use daily_wip_by_blocked_stalled_chart instead.'
-    execute_chart DailyWipByBlockedStalledChart.new
-  end
-
-  def expedited_chart priority_name = nil
-    if priority_name
-      deprecated message: 'priority name should no longer be passed into the chart. Specify it in the ' \
-        'board declaration. See https://github.com/mikebowler/jira-export/wiki/Deprecated',
-        date: '2022-12-26'
-    end
+  def expedited_chart
     execute_chart ExpeditedChart.new
   end
 
@@ -125,11 +105,11 @@ class HtmlReportConfig
   end
 
   def random_color
-    "\##{Random.bytes(3).unpack1('H*')}"
+    "##{Random.bytes(3).unpack1('H*')}"
   end
 
   def html string, type: :body
-    raise "Unexpected type: #{type}" unless [:body, :header].include? type
+    raise "Unexpected type: #{type}" unless %i[body header].include? type
 
     @sections << [string, type]
   end
@@ -161,11 +141,6 @@ class HtmlReportConfig
     end
   end
 
-  def discarded_changes_report
-    puts 'Deprecated(discarded_changes_report) No need to specify this anymore as this information is ' \
-     'now included in the data quality checks.'
-  end
-
   def dependency_chart &block
     execute_chart DependencyChart.new block
   end

data/lib/jirametrics/issue.rb

@@ -54,11 +54,6 @@ class Issue
     Status.new raw: @raw['fields']['status']
   end
 
-  def status_id
-    puts 'DEPRECATED(Issue.status_id) Call Issue.status.id instead'
-    status.id
-  end
-
   def labels = @raw['fields']['labels'] || []
 
   def author = @raw['fields']['creator']&.[]('displayName') || ''
@@ -270,7 +265,6 @@ class Issue
     # By doing this, we're able to eliminate a lot of duplicated code in charts.
     mock_change = ChangeItem.new time: end_time, author: '', artificial: true, raw: { 'field' => '' }
     (changes + [mock_change]).each do |change|
-
       previous_was_active = false if check_for_stalled(
         change_time: change.time,
         previous_change_time: previous_change_time,
@@ -388,7 +382,7 @@ class Issue
       if expedited_names.include? change.value
         expedited_start = change.time.to_date if expedited_start.nil?
       else
-        return true if expedited_start && (expedited_start..change.time.to_date).include?(date)
+        return true if expedited_start && (expedited_start..change.time.to_date).cover?(date)
 
         expedited_start = nil
       end

data/lib/jirametrics/issue_link.rb

@@ -19,13 +19,6 @@ class IssueLink
   end
 
   def direction
-    assert_jira_behaviour_false(raw['inwardIssue'].nil? && raw['outwardIssue'].nil?) do
-      "Found an issue link with neither inward nor outward references: #{raw}"
-    end
-    assert_jira_behaviour_false(raw['inwardIssue'] && raw['outwardIssue']) do
-      "Found an issue link that has both inward and outward references in the same link: #{raw}"
-    end
-
     if raw['inwardIssue']
       :inward
     else

data/lib/jirametrics/jira_gateway.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'English'
+
+class JiraGateway
+  attr_accessor :ignore_ssl_errors, :jira_url
+
+  def initialize file_system:
+    @file_system = file_system
+  end
+
+  def call_url relative_url:
+    command = make_curl_command url: "#{@jira_url}#{relative_url}"
+    JSON.parse call_command command
+  end
+
+  def call_command command
+    @file_system.log "  #{command.gsub(/\s+/, ' ')}"
+    result = `#{command}`
+    @file_system.log result unless $CHILD_STATUS.success?
+    return result if $CHILD_STATUS.success?
+
+    @file_system.log "Failed call with exit status #{$CHILD_STATUS.exitstatus}."
+    raise "Failed call with exit status #{$CHILD_STATUS.exitstatus}. " \
+      "See #{@file_system.logfile_name} for details"
+  end
+
+  def load_jira_config jira_config
+    @jira_url = jira_config['url']
+    raise "Must specify URL in config" if @jira_url.nil?
+
+    @jira_email = jira_config['email']
+    @jira_api_token = jira_config['api_token']
+    @jira_personal_access_token = jira_config['personal_access_token']
+
+    raise 'When specifying an api-token, you must also specify email' if @jira_api_token && !@jira_email
+
+    if @jira_api_token && @jira_personal_access_token
+      raise "You can't specify both an api-token and a personal-access-token. They don't work together."
+    end
+
+    @cookies = (jira_config['cookies'] || []).collect { |key, value| "#{key}=#{value}" }.join(';')
+  end
+
+  def make_curl_command url:
+    command = 'curl'
+    command += ' -s'
+    command += ' -k' if @ignore_ssl_errors
+    command += " --cookie #{@cookies.inspect}" unless @cookies.empty?
+    command += " --user #{@jira_email}:#{@jira_api_token}" if @jira_api_token
+    command += " -H \"Authorization: Bearer #{@jira_personal_access_token}\"" if @jira_personal_access_token
+    command += ' --request GET'
+    command += ' --header "Accept: application/json"'
+    command += " --url \"#{url}\""
+    command
+  end
+end