jirametrics 2.13 → 2.30

data/lib/jirametrics/project_config.rb

@@ -6,7 +6,7 @@ require 'jirametrics/status_collection'
 class ProjectConfig
   attr_reader :target_path, :jira_config, :all_boards, :possible_statuses,
     :download_config, :file_configs, :exporter, :data_version, :name, :board_configs,
-    :settings, :aggregate_config, :discarded_changes_data, :users
+    :settings, :aggregate_config, :discarded_changes_data, :users, :fix_versions
   attr_accessor :time_range, :jira_url, :id
 
   def initialize exporter:, jira_config:, block:, target_path: '.', name: '', id: nil
@@ -23,6 +23,7 @@ class ProjectConfig
     @settings = load_settings
     @id = id
     @has_loaded_data = false
+    @fix_versions = []
   end
 
   def evaluate_next_level
@@ -40,17 +41,20 @@ class ProjectConfig
     @id = guess_project_id
     load_project_metadata
     load_sprints
+    load_fix_versions
     load_users
+    resolve_blocked_stalled_status_settings
   end
 
   def run load_only: false
     return if @exporter.downloading?
 
     load_data unless aggregated_project?
-    anonymize_data if @anonymizer_needed
 
     return if load_only
 
+    anonymize_data if @anonymizer_needed
+
     @file_configs.each do |file_config|
       file_config.run
     end
@@ -58,7 +62,19 @@ class ProjectConfig
 
   def load_settings
     # This is the weird exception that we don't ever want mocked out so we skip FileSystem entirely.
-    JSON.parse(File.read(File.join(__dir__, 'settings.json'), encoding: 'UTF-8'))
+    settings = JSON.parse(File.read(File.join(__dir__, 'settings.json'), encoding: 'UTF-8'))
+
+    if settings['blocked_color']
+      file_system.deprecated message: 'blocked color should be set via css now', date: '2024-05-03'
+    end
+    if settings['stalled_color']
+      file_system.deprecated message: 'stalled color should be set via css now', date: '2024-05-03'
+    end
+
+    settings['blocked_statuses'] = StatusCollection.new
+    settings['stalled_statuses'] = StatusCollection.new
+
+    stringify_keys(settings)
   end
 
   def guess_project_id
@@ -82,6 +98,12 @@ class ProjectConfig
     !!@aggregate_config
   end
 
+  def aggregate_project_names
+    return [] unless aggregated_project?
+
+    @aggregate_config.included_projects.filter_map(&:name)
+  end
+
   def download &block
     raise 'Not allowed to have multiple download blocks in one project' if @download_config
     raise 'Not allowed to have both an aggregate and a download section. Pick only one.' if @aggregate_config
@@ -114,10 +136,14 @@ class ProjectConfig
   def file_prefix prefix
     # The file_prefix has to be set before almost everything else. It really should have been an attribute
     # on the project declaration itself. Hindsight is 20/20.
+
+    # There can only be one of these
     if @file_prefix
-      raise "file_prefix should only be set once. Was #{@file_prefix.inspect} and now changed to #{prefix.inspect}."
+      raise "file_prefix can only be set once. Was #{@file_prefix.inspect} and now changed to #{prefix.inspect}."
     end
 
+    raise_if_prefix_already_used(prefix)
+
     @file_prefix = prefix
 
     # Yes, this is a wierd place to be initializing this. Unfortunately, it has to happen after the file_prefix
@@ -130,8 +156,32 @@ class ProjectConfig
     @file_prefix
   end
 
-  def get_file_prefix # rubocop:disable Naming/AccessorMethodName
-    raise 'file_prefix has not been set yet. Move it to the top of the project declaration.' unless @file_prefix
+  def validate_discard_status status_name
+    return if status_name == :backlog
+    return if possible_statuses.empty? # not yet downloaded; skip validation
+
+    found = possible_statuses.find_all_by_name status_name
+    return unless found.empty?
+
+    raise "discard_changes_before: Status #{status_name.inspect} not found. " \
+      "Possible statuses are: #{possible_statuses}"
+  end
+
+  def raise_if_prefix_already_used prefix
+    @exporter.project_configs.each do |project|
+      next unless project.get_file_prefix(raise_if_not_set: false) == prefix && project.target_path == target_path
+
+      raise "Project #{name.inspect} specifies file prefix #{prefix.inspect}, " \
+        "but that is already used by project #{project.name.inspect} in the same target path #{target_path.inspect}. " \
+        'This is almost guaranteed to be too much copy and paste in your configuration. ' \
+        'File prefixes must be unique within a directory.'
+    end
+  end
+
+  def get_file_prefix raise_if_not_set: true
+    if @file_prefix.nil? && raise_if_not_set
+      raise 'file_prefix has not been set yet. Move it to the top of the project declaration.'
+    end
 
     @file_prefix
   end
@@ -241,9 +291,16 @@ class ProjectConfig
   end
 
   def load_board board_id:, filename:
-    board = Board.new(
-      raw: file_system.load_json(filename), possible_statuses: @possible_statuses
-    )
+    raw = file_system.load_json(filename)
+
+    features_filename = File.join(@target_path, "#{get_file_prefix}_board_#{board_id}_features.json")
+    features = if file_system.file_exist?(features_filename)
+                 BoardFeature.from_raw(file_system.load_json(features_filename))
+               else
+                 []
+               end
+
+    board = Board.new(raw: raw, possible_statuses: @possible_statuses, features: features)
     board.project_config = self
     @all_boards[board_id] = board
   end
@@ -278,8 +335,9 @@ class ProjectConfig
     file_system.foreach(@target_path) do |file|
       next unless file =~ /^#{get_file_prefix}_board_(\d+)_sprints_\d+.json$/
 
+      board_id = $1.to_i
       file_path = File.join(@target_path, file)
-      board = @all_boards[$1.to_i]
+      board = @all_boards[board_id]
       unless board
         @exporter.file_system.log(
           'Found sprint data but can\'t find a matching board in config. ' \
@@ -299,6 +357,13 @@ class ProjectConfig
     end
   end
 
+  def load_fix_versions
+    filename = File.join(@target_path, "#{get_file_prefix}_fix_versions.json")
+    return unless file_system.file_exist?(filename)
+
+    @fix_versions = file_system.load_json(filename).map { |raw| FixVersion.new(raw) }
+  end
+
   def load_project_metadata
     filename = File.join @target_path, "#{get_file_prefix}_meta.json"
     json = file_system.load_json(filename)
@@ -335,6 +400,25 @@ class ProjectConfig
     json.each { |user_data| @users << User.new(raw: user_data) }
   end
 
+  def attach_github_prs
+    filename = File.join(@target_path, "#{get_file_prefix}_github_prs.json")
+    return unless File.exist?(filename)
+
+    prs_by_issue_key = Hash.new { |h, k| h[k] = [] }
+    file_system.load_json(filename).each do |raw|
+      pr = PullRequest.new(raw: raw)
+      pr.issue_keys.each { |key| prs_by_issue_key[key] << pr }
+    end
+
+    @issues.each { |issue| issue.github_prs = prs_by_issue_key[issue.key] }
+  end
+
+  def atlassian_document_format
+    @atlassian_document_format ||= AtlassianDocumentFormat.new(
+      users: @users, timezone_offset: exporter.timezone_offset
+    )
+  end
+
   def to_time string, end_of_day: false
     time = end_of_day ? '23:59:59' : '00:00:00'
     string = "#{string}T#{time}#{exporter.timezone_offset}" if string.match?(/^\d{4}-\d{2}-\d{2}$/)
@@ -369,7 +453,7 @@ class ProjectConfig
   # To be used by the aggregate_config only. Not intended to be part of the public API
   def add_issues issues_list
     @issues = IssueCollection.new if @issues.nil?
-    @all_boards = {}
+    @all_boards ||= {}
 
     issues_list.each do |issue|
       @issues << issue
@@ -411,6 +495,7 @@ class ProjectConfig
       # attached them in the appropriate places, remove any that aren't part of that initial set.
       issues.reject! { |i| !i.in_initial_query? } # rubocop:disable Style/InverseMethods
       @issues = issues
+      attach_github_prs
     end
 
     @issues
@@ -526,9 +611,12 @@ class ProjectConfig
   end
 
   def discard_changes_before status_becomes: nil, &block
+    cycletimes_touched = Set.new
     if status_becomes
       status_becomes = [status_becomes] unless status_becomes.is_a? Array
 
+      status_becomes.each { |status_name| validate_discard_status status_name }
+
       block = lambda do |issue|
         trigger_statuses = status_becomes.collect do |status_name|
           if status_name == :backlog
@@ -554,10 +642,11 @@ class ProjectConfig
       cutoff_time = block.call(issue)
       next if cutoff_time.nil?
 
-      original_start_time = issue.board.cycletime.started_stopped_times(issue).first
+      original_start_time = issue.started_stopped_times.first
       next if original_start_time.nil?
 
       issue.discard_changes_before cutoff_time
+      cycletimes_touched << issue.board.cycletime
 
       next unless cutoff_time
       next if original_start_time > cutoff_time # ie the cutoff would have made no difference.
@@ -568,5 +657,32 @@ class ProjectConfig
         issue: issue
       }
     end
+
+    cycletimes_touched.each { |c| c.flush_cache }
+  end
+
+  def stringify_keys value
+    case value
+    when Hash then value.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
+    when Array then value.map { |v| stringify_keys(v) }
+    else value
+    end
+  end
+
+  def resolve_blocked_stalled_status_settings
+    %w[blocked_statuses stalled_statuses].each do |key|
+      next if @settings[key].is_a?(StatusCollection)
+
+      collection = StatusCollection.new
+      @settings[key].each do |identifier|
+        statuses = @possible_statuses.find_all_by_name(identifier)
+        if statuses.empty?
+          file_system.warning "Status #{identifier.inspect} in #{key} not found. Ignoring."
+        else
+          statuses.each { |status| collection << status }
+        end
+      end
+      @settings[key] = collection
+    end
   end
 end

data/lib/jirametrics/pull_request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'jirametrics/pull_request_review'
+
+class PullRequest
+  attr_reader :raw
+
+  def initialize raw:
+    @raw = raw
+  end
+
+  def number     = @raw['number']
+  def repo       = @raw['repo']
+  def url        = @raw['url']
+  def title      = @raw['title']
+  def branch     = @raw['branch']
+  def state      = @raw['state']
+  def issue_keys = @raw['issue_keys']
+
+  def opened_at = Time.parse(@raw['opened_at'])
+  def closed_at = @raw['closed_at'] ? Time.parse(@raw['closed_at']) : nil
+  def merged_at = @raw['merged_at'] ? Time.parse(@raw['merged_at']) : nil
+
+  def reviews       = (@raw['reviews'] || []).map { |r| PullRequestReview.new(raw: r) }
+  def additions     = @raw['additions']
+  def deletions     = @raw['deletions']
+  def changed_files = @raw['changed_files']
+  def lines_changed = (additions || 0) + (deletions || 0)
+end

data/lib/jirametrics/pull_request_cycle_time_histogram.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class PullRequestCycleTimeHistogram < TimeBasedHistogram
+  def initialize block
+    super()
+
+    @cycletime_unit = :days
+    @x_axis_title = 'Cycle time in days'
+
+    header_text 'PR Histogram'
+    description_text <<-HTML
+      <div class="p">
+        This cycletime Histogram shows how many pull requests completed in a certain timeframe. This can be
+        useful for determining how many different types of work are flowing through, based on the
+        lengths of time they take.
+      </div>
+    HTML
+
+    init_configuration_block(block) do
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
+      end
+    end
+  end
+
+  def cycletime_unit unit
+    unless %i[minutes hours days].include?(unit)
+      raise ArgumentError, "cycletime_unit must be :minutes, :hours, or :days, got #{unit.inspect}"
+    end
+
+    @cycletime_unit = unit
+    @x_axis_title = "Cycle time in #{unit}"
+  end
+
+  def all_items
+    result = []
+    issues.each do |issue|
+      next unless issue.github_prs
+
+      issue.github_prs.each do |pr|
+        next unless pr.closed_at
+
+        result << pr
+      end
+    end
+    result.uniq
+  end
+
+  def value_for_item item
+    divisor = { minutes: 60.0, hours: 3600.0, days: 86_400.0 }[@cycletime_unit]
+    ((item.closed_at - item.opened_at) / divisor).ceil
+  end
+
+  def label_cycletime value
+    case @cycletime_unit
+    when :minutes then label_minutes(value)
+    when :hours then label_hours(value)
+    when :days then label_days(value)
+    end
+  end
+
+  def title_for_item count:, value:
+    "#{count} PR#{'s' unless count == 1} closed in #{label_cycletime value}"
+  end
+
+  def sort_items items
+    items.sort_by(&:opened_at)
+  end
+
+  def label_for_item item, hint:
+    label = "#{item.number} #{item.title}"
+    label << hint if hint
+    label
+  end
+end

data/lib/jirametrics/pull_request_cycle_time_scatterplot.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
+  def initialize block
+    super()
+
+    @cycletime_unit = :days
+    @y_axis_title = 'Cycle time in days'
+
+    header_text 'Pull Request (PR) Scatterplot'
+    description_text <<-HTML
+      <div class="p">
+        This graph shows the cycle time for all closed pull requests (time from opened to closed).
+      </div>
+      #{describe_non_working_days}
+    HTML
+
+    init_configuration_block(block) do
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
+      end
+    end
+  end
+
+  def cycletime_unit unit
+    unless %i[minutes hours days].include?(unit)
+      raise ArgumentError, "cycletime_unit must be :minutes, :hours, or :days, got #{unit.inspect}"
+    end
+
+    @cycletime_unit = unit
+    @y_axis_title = "Cycle time in #{unit}"
+  end
+
+  def all_items
+    result = []
+    issues.each do |issue|
+      issue.github_prs&.each do |pr|
+        result << pr if pr.closed_at
+      end
+    end
+    result
+  end
+
+  def x_value pull_request
+    pull_request.closed_at
+  end
+
+  def y_value pull_request
+    if @cycletime_unit == :days
+      tz = timezone_offset || '+00:00'
+      opened = pull_request.opened_at.getlocal(tz).to_date
+      closed = pull_request.closed_at.getlocal(tz).to_date
+      (closed - opened).to_i + 1
+    else
+      divisor = { minutes: 60, hours: 3600 }[@cycletime_unit]
+      ((pull_request.closed_at - pull_request.opened_at) / divisor).round
+    end
+  end
+
+  def label_cycletime value
+    case @cycletime_unit
+    when :minutes then label_minutes(value)
+    when :hours then label_hours(value)
+    when :days then label_days(value)
+    end
+  end
+
+  def title_value pull_request, rules: nil
+    age_label = label_cycletime y_value(pull_request)
+    keys = pull_request.issue_keys.join(', ')
+    "#{keys} | #{pull_request.title} | #{rules.label} | Age:#{age_label}#{lines_changed_text(pull_request)}"
+  end
+
+  def lines_changed_text pull_request
+    return '' unless pull_request.changed_files
+
+    additions = pull_request.additions || 0
+    deletions = pull_request.deletions || 0
+    text = +' | Lines changed: ['
+    text << "+#{to_human_readable additions}" unless additions.zero?
+    text << ' ' if additions != 0 && deletions != 0
+    text << "-#{to_human_readable deletions}" unless deletions.zero?
+    text << "], Files changed: #{to_human_readable pull_request.changed_files}"
+    text
+  end
+end

data/lib/jirametrics/pull_request_review.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'time'
+
+class PullRequestReview
+  def initialize raw:
+    @raw = raw
+  end
+
+  def author = @raw['author']
+  def state = @raw['state']
+  def submitted_at = Time.parse(@raw['submitted_at'])
+end

data/lib/jirametrics/raw_javascript.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# When strings are serialized into JSON, they're converted to actual strings. The purpose
+# of this class is to allow raw javascript to be passed through.
+class RawJavascript
+  def initialize content
+    @content = content
+  end
+
+  def to_json(*_args)
+    @content
+  end
+
+  def == other
+    other.is_a?(RawJavascript) && to_json == other.to_json
+  end
+end

data/lib/jirametrics/settings.json

@@ -7,5 +7,9 @@
   "flagged_means_blocked": true,
 
   "expedited_priority_names": ["Critical", "Highest"],
-  "priority_order": ["Lowest", "Low", "Medium", "High", "Highest"]
+  "priority_order": ["Lowest", "Low", "Medium", "High", "Highest"],
+
+  "cache_cycletime_calculations": true,
+
+  "date_annotations": []
 }

data/lib/jirametrics/sprint.rb

@@ -13,6 +13,7 @@ class Sprint
   def id = @raw['id']
   def active? = (@raw['state'] == 'active')
   def closed? = (@raw['state'] == 'closed')
+  def future? = (@raw['state'] == 'future')
 
   def completed_at? time
     completed_at = completed_time
@@ -36,6 +37,17 @@ class Sprint
   def goal = @raw['goal']
   def name = @raw['name']
 
+  def day_count
+    return '' if future?
+
+    if closed?
+      days = (completed_time.to_date - start_time.to_date).to_i + 1
+    else
+      days = (end_time.to_date - start_time.to_date).to_i + 1
+    end
+    "#{days} days"
+  end
+
   private
 
   def parse_time time_string

data/lib/jirametrics/sprint_burndown.rb

@@ -29,6 +29,8 @@ class SprintBurndown < ChartBase
       </div>
       #{describe_non_working_days}
     TEXT
+    @x_axis_title = 'Date'
+    @y_axis_title = 'Items remaining'
   end
 
   def options= arg
@@ -48,8 +50,9 @@ class SprintBurndown < ChartBase
   end
 
   def run
-    sprints = sprints_in_time_range all_boards[board_id]
-    return nil if sprints.empty?
+    return nil unless current_board.scrum?
+
+    sprints = sprints_in_time_range current_board
 
     change_data_by_sprint = {}
     sprints.each do |sprint|
@@ -63,7 +66,7 @@ class SprintBurndown < ChartBase
     result = +''
     result << render_top_text(binding)
 
-    possible_colours = (1..5).collect { |i| CssVariable["--sprint-burndown-sprint-color-#{i}"] }
+    possible_colours = (1..ChartBase::OKABE_ITO_PALETTE.size).collect { |i| CssVariable["--sprint-burndown-sprint-color-#{i}"] }
     charts_to_generate = []
     charts_to_generate << [:data_set_by_story_points, 'Story Points'] if @use_story_points
     charts_to_generate << [:data_set_by_story_counts, 'Story Count'] if @use_story_counts
@@ -110,6 +113,9 @@ class SprintBurndown < ChartBase
 
   def sprints_in_time_range board
     board.sprints.select do |sprint|
+      # If it's never been started then it's just a holding area. Ignore it.
+      next if sprint.future?
+
       sprint_end_time = sprint.completed_time || sprint.end_time
       sprint_start_time = sprint.start_time
       next false if sprint_start_time.nil?
@@ -128,7 +134,7 @@ class SprintBurndown < ChartBase
 
     estimate_display_name = current_board.estimation_configuration.display_name
 
-    issue_completed_time = issue.board.cycletime.started_stopped_times(issue).last
+    issue_completed_time = issue.started_stopped_times.last
     completed_has_been_tracked = false
 
     issue.changes.each do |change|

data/lib/jirametrics/status.rb

@@ -36,7 +36,7 @@ class Status
   end
 
   def self.from_raw raw
-    raise "raw cannot be nil" if raw.nil?
+    raise 'raw cannot be nil' if raw.nil?
 
     category_config = raw['statusCategory']
     raise "statusCategory can't be nil in #{category_config.inspect}" if category_config.nil?

data/lib/jirametrics/stitcher.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class Stitcher < HtmlGenerator
+  class StitchContent
+    include ValueEquality
+
+    attr_reader :file, :title, :content, :type
+
+    def initialize file:, title:, type:, content:
+      @file = file
+      @title = title
+      @content = content
+      @type = type
+    end
+  end
+
+  attr_reader :loaded_files, :all_stitches
+
+  def initialize file_system:
+    super()
+    self.file_system = file_system
+    @all_stitches = []
+    @loaded_files = []
+  end
+
+  def run stitch_file:
+    output_filename = make_output_filename stitch_file
+    file_system.log "Creating file #{output_filename.inspect}", also_write_to_stderr: true
+    erb = ERB.new file_system.load(stitch_file)
+    @sections = [[erb.result(binding), :body]]
+    create_html output_filename: output_filename, settings: {}
+  end
+
+  def make_output_filename input_filename
+    if /^(.+)\.erb$/ =~ input_filename
+      "#{$1}.html"
+    else
+      "#{input_filename}.html"
+    end
+  end
+
+  def grab_by_title title, from_file:, type: 'chart'
+    parse_file from_file
+    stitch_content = @all_stitches.find { |s| s.file == from_file && s.title == title && s.type == type }
+    return stitch_content.content if stitch_content
+
+    file_system.error "Unable to find content in file #{from_file.inspect} matching title: #{title.inspect}"
+    ''
+  end
+
+  def parse_file filename
+    return false if @loaded_files.include? filename
+
+    # To match: <!-- seam-start | chart78 | GithubPrScatterplot | PR Scatterplot | chart -->
+    regex = /^<!-- seam-(?<seam>start|end) \| (?<id>[^|]+) \| (?<clazz>[^|]+) \| (?<title>[^|]+) \| (?<type>[^|]+) -->$/
+    content = nil
+    file_system.load(filename).lines do |line|
+      matches = line.match(regex)
+      if matches
+        if matches[:seam] == 'start'
+          content = +''
+        else
+          if content.nil? || content.strip.empty?
+            file_system.warning "Seam found with no content in #{filename.inspect}: " \
+              "id=#{matches[:id].strip.inspect}, class=#{matches[:clazz].strip.inspect}, " \
+              "title=#{matches[:title].strip.inspect}"
+          end
+          @all_stitches << Stitcher::StitchContent.new(
+            file: filename, title: matches[:title], type: matches[:type], content: content
+          )
+          content = nil
+        end
+      elsif content
+        content << line
+      end
+    end
+
+    @loaded_files << filename
+    true
+  end
+end

data/lib/jirametrics/throughput_by_completed_resolution_chart.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'jirametrics/throughput_chart'
+
+class ThroughputByCompletedResolutionChart < ThroughputChart
+  def initialize block
+    super
+    header_text 'Throughput, grouped by completion status and resolution'
+    description_text nil
+  end
+
+  def default_grouping_rules issue, rules
+    status, resolution = issue.status_resolution_at_done
+    if resolution
+      rules.label = "#{status.name}:#{resolution}"
+      rules.label_hint = "Status: #{status.name.inspect}:#{status.id}, resolution: #{resolution.inspect}"
+    else
+      rules.label = status.name
+      rules.label_hint = "Status: #{status.name.inspect}:#{status.id}"
+    end
+  end
+end