jirametrics 2.22 → 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
@@ -67,7 +71,10 @@ class ProjectConfig
       file_system.deprecated message: 'stalled color should be set via css now', date: '2024-05-03'
     end
 
-    settings
+    settings['blocked_statuses'] = StatusCollection.new
+    settings['stalled_statuses'] = StatusCollection.new
+
+    stringify_keys(settings)
   end
 
   def guess_project_id
@@ -91,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
@@ -143,6 +156,17 @@ class ProjectConfig
     @file_prefix
   end
 
+  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
@@ -267,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
@@ -326,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)
@@ -362,6 +400,19 @@ 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
@@ -402,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
@@ -444,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
@@ -563,6 +615,8 @@ class ProjectConfig
     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
@@ -588,7 +642,7 @@ 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
@@ -606,4 +660,29 @@ class ProjectConfig
 
     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

@@ -10,4 +10,8 @@ class RawJavascript
   def to_json(*_args)
     @content
   end
+
+  def == other
+    other.is_a?(RawJavascript) && to_json == other.to_json
+  end
 end

data/lib/jirametrics/settings.json

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

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
@@ -64,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
@@ -132,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

@@ -44,7 +44,8 @@ class Stitcher < HtmlGenerator
     stitch_content = @all_stitches.find { |s| s.file == from_file && s.title == title && s.type == type }
     return stitch_content.content if stitch_content
 
-    raise "Unable to find content in file #{from_file.inspect} matching title: #{title.inspect}"
+    file_system.error "Unable to find content in file #{from_file.inspect} matching title: #{title.inspect}"
+    ''
   end
 
   def parse_file filename
@@ -59,6 +60,11 @@ class Stitcher < HtmlGenerator
         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
           )

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

data/lib/jirametrics/throughput_chart.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cgi'
+
 class ThroughputChart < ChartBase
   include GroupableIssueChart
 
@@ -10,42 +12,54 @@ class ThroughputChart < ChartBase
 
     header_text 'Throughput Chart'
     description_text <<-TEXT
-      <div class="p">
-        This chart shows how many items we completed per week
+      <div>Throughput data is very useful for#{' '}
+        <a href="https://blog.mikebowler.ca/2024/06/02/probabilistic-forecasting/">probabilistic forecasting</a>,
+        to determine when we'll be done. Try it now with the
+        <a href="<%= throughput_forecaster_url %>" target="_blank" rel="noopener noreferrer">
+        Focused Objective throughput forecaster,</a> to see how long it would take to complete all of the
+        <%= @not_started_count %> items you currently have in your backlog.
       </div>
       #{describe_non_working_days}
     TEXT
+    @x_axis_title = nil
+    @y_axis_title = 'Count of items'
 
     init_configuration_block(block) do
-      grouping_rules do |issue, rule|
-        rule.label = issue.type
-        rule.color = color_for type: issue.type
-      end
+      grouping_rules { |issue, rule| default_grouping_rules(issue, rule) }
     end
   end
 
   def run
+    # This is saved as an instance variable so that it's accessible later when rendering the description text
+    @not_started_count = issues.count { |issue| issue.started_stopped_times.first.nil? }
+
     completed_issues = completed_issues_in_range include_unstarted: true
     rules_to_issues = group_issues completed_issues
     data_sets = []
-    if rules_to_issues.size > 1
-      data_sets << weekly_throughput_dataset(
-        completed_issues: completed_issues,
-        label: 'Totals',
-        color: CssVariable['--throughput_chart_total_line_color'],
-        dashed: true
-      )
-    end
+    total_data_set = weekly_throughput_dataset(
+      completed_issues: completed_issues,
+      label: 'Totals',
+      color: CssVariable['--throughput_chart_total_line_color'],
+      dashed: true
+    )
+    @throughput_samples = total_data_set[:data].collect { |d| d[:y] }
+    data_sets << total_data_set if rules_to_issues.size > 1
 
     rules_to_issues.each_key do |rules|
       data_sets << weekly_throughput_dataset(
-        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color
+        completed_issues: rules_to_issues[rules], label: rules.label, color: rules.color,
+        label_hint: rules.label_hint
       )
     end
 
     wrap_and_render(binding, __FILE__)
   end
 
+  def default_grouping_rules issue, rule
+    rule.label = issue.type
+    rule.color = color_for type: issue.type
+  end
+
   def calculate_time_periods
     first_day = @date_range.begin
     first_day = case first_day.wday
@@ -65,10 +79,22 @@ class ThroughputChart < ChartBase
     end
   end
 
-  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false
+  def calculate_custom_periods
+    last_days = @issue_periods.values.compact.uniq.sort
+    last_days.each_with_index.map do |last_day, i|
+      first_day = i.zero? ? @date_range.begin : last_days[i - 1] + 1
+      first_day..last_day
+    end
+  end
+
+  def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false, label_hint: nil
+    periods = @issue_periods&.values&.any? ? calculate_custom_periods : calculate_time_periods
     result = {
       label: label,
-      data: throughput_dataset(periods: calculate_time_periods, completed_issues: completed_issues),
+      label_hint: label_hint,
+      data: throughput_dataset(
+        periods: periods, completed_issues: completed_issues, label_hint: label_hint
+      ),
       fill: false,
       showLine: true,
       borderColor: color,
@@ -79,20 +105,44 @@ class ThroughputChart < ChartBase
     result
   end
 
-  def throughput_dataset periods:, completed_issues:
+  def throughput_forecaster_url
+    params = {
+      throughputMode: 'data',
+      samplesText: @throughput_samples.join(','),
+      storyLow: @not_started_count,
+      storyHigh: @not_started_count
+    }
+
+    query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
+    "https://focusedobjective.com/throughput?#{query}"
+  end
+
+  def throughput_dataset periods:, completed_issues:, label_hint: nil
+    custom_mode = @issue_periods&.values&.any?
     periods.collect do |period|
       closed_issues = completed_issues.filter_map do |issue|
-        stop_date = issue.board.cycletime.started_stopped_dates(issue).last
-        [stop_date, issue] if stop_date && period.include?(stop_date)
+        stop_date = issue.started_stopped_dates.last
+        next unless stop_date
+
+        if custom_mode
+          [stop_date, issue] if @issue_periods[issue] == period.end
+        elsif period.include?(stop_date)
+          [stop_date, issue]
+        end
       end
 
       date_label = "on #{period.end}"
       date_label = "between #{period.begin} and #{period.end}" unless period.begin == period.end
 
-      { y: closed_issues.size,
+      with_label_hint = label_hint ? " with #{label_hint}" : ''
+      {
+        y: closed_issues.size,
         x: "#{period.end}T23:59:59",
-        title: ["#{closed_issues.size} items completed #{date_label}"] +
-          closed_issues.collect { |_stop_date, issue| "#{issue.key} : #{issue.summary}" }
+        title: ["#{closed_issues.size} items closed#{with_label_hint} #{date_label}"] +
+          closed_issues.collect do |_stop_date, issue|
+            hint = @issue_hints&.fetch(issue, nil)
+            "#{issue.key} : #{issue.summary}#{" #{hint}" if hint}"
+          end
       }
     end
   end