jirametrics 2.31 → 3.0

data/lib/jirametrics/issue.rb

@@ -26,7 +26,7 @@ class Issue
     return unless @raw['fields']
 
     # If this is an older pull of data then comments may not be there.
-    load_comments_into_changes if @raw['fields']['comment']
+    load_comments_into_changes if raw_fields['comment']
 
     # It might appear that Jira already returns these in order but we've found different
     # versions of Server/Cloud return the changelog in different orders so we sort them.
@@ -36,40 +36,46 @@ class Issue
     # not showing up in the change log. Create some artificial entries to capture those.
     @changes = [
       fabricate_change(field_name: 'status'),
-      fabricate_change(field_name: 'priority')
+      fabricate_change(field_name: 'priority'),
+      fabricate_sprint_change
     ].compact + @changes
-  rescue # rubocop:disable Style/RescueStandardError
+  rescue # rubocop:disable Style/RescueStandardError -- deliberately broad: any failure is re-raised with context
     # All we're doing is adding information to the existing exception and letting it propogate up
     raise "Unable to initialize #{raw['key']}"
   end
 
   def key = @raw['key']
 
-  def type = @raw['fields']['issuetype']['name']
-  def type_icon_url = @raw['fields']['issuetype']['iconUrl']
+  # 'fields' is the one part of the issue JSON that must always be present -- its absence means the
+  # payload is malformed. (Linked-issue fragments legitimately have no fields; that case is guarded in
+  # initialize, which returns before any of the fields-based accessors below can run.)
+  def raw_fields
+    @raw['fields'] || raise("Issue(#{@raw['key']}) has no 'fields'; is this an Issue JSON?")
+  end
+
+  def type = raw_fields['issuetype']['name']
+  def type_icon_url = raw_fields['issuetype']['iconUrl']
 
   def priority_name = @raw.dig('fields', 'priority', 'name')
   def priority_url = @raw.dig('fields', 'priority', 'iconUrl')
 
-  def summary = @raw['fields']['summary']
+  def summary = raw_fields['summary']
 
-  def labels = @raw['fields']['labels'] || []
+  def labels = raw_fields['labels'] || []
 
-  def author = @raw['fields']['creator']&.[]('displayName') || ''
+  def author = raw_fields['creator']&.[]('displayName') || ''
 
-  def resolution = @raw['fields']['resolution']&.[]('name')
+  def resolution = raw_fields['resolution']&.[]('name')
 
   def status
-    @status = Status.from_raw(@raw['fields']['status']) unless @status
+    @status ||= Status.from_raw(raw_fields['status'])
     @status
   end
 
-  def status= status
-    @status = status
-  end
+  attr_writer :status
 
   def due_date
-    text = @raw['fields']['duedate']
+    text = raw_fields['duedate']
     text.nil? ? nil : Date.parse(text)
   end
 
@@ -79,11 +85,11 @@ class Issue
   end
 
   def key_as_i
-    key =~ /-(\d+)$/ ? $1.to_i : 0
+    /-(?<number>\d+)$/ =~ key ? number.to_i : 0
   end
 
   def component_names
-    @raw['fields']['components']&.collect { |component| component['name'] } || []
+    raw_fields['components']&.collect { |component| component['name'] } || []
   end
 
   def first_time_in_status *status_names
@@ -103,7 +109,7 @@ class Issue
       next unless change.labels?
 
       change_labels = change.value.split
-      return change if change_labels.any? { |l| labels.include?(l) }
+      return change if change_labels.intersect?(labels)
     end
     nil
   end
@@ -213,22 +219,24 @@ class Issue
     visible_status_ids = board.visible_columns.collect(&:status_ids).flatten
     return first_time_in_status(*visible_status_ids) unless board.scrum?
 
-    # For scrum boards, an issue is only visible when BOTH conditions are true simultaneously:
-    # 1. Its status is in a visible column
-    # 2. It is in an active sprint
-    # At each moment one condition becomes true, check if the other is already true.
-    candidates = []
+    # On scrum boards an issue is only visible when its status is in a visible column AND it is in an
+    # active sprint. Each source below is a moment when the second condition became true while the first
+    # already held; the earliest of them is when it first became visible.
+    candidates = visible_status_changes_in_active_sprint(visible_status_ids) +
+                 sprint_entries_while_in_visible_status(visible_status_ids)
+    candidates.min_by(&:time)
+  end
 
-    status_changes.each do |change|
-      next unless visible_status_ids.include?(change.value_id)
-      candidates << change if in_active_sprint_at?(change.time)
+  def visible_status_changes_in_active_sprint visible_status_ids
+    status_changes.select do |change|
+      visible_status_ids.include?(change.value_id) && in_active_sprint_at?(change.time)
     end
+  end
 
-    sprint_entry_events.each do |effective_time, representative_change|
-      candidates << representative_change if in_visible_status_at?(effective_time, visible_status_ids)
+  def sprint_entries_while_in_visible_status visible_status_ids
+    sprint_entry_events.filter_map do |effective_time, representative_change|
+      representative_change if in_visible_status_at?(effective_time, visible_status_ids)
     end
-
-    candidates.min_by(&:time)
   end
 
   def reasons_not_visible_on_board
@@ -244,87 +252,113 @@ class Issue
     reasons_not_visible_on_board.empty?
   end
 
-  # If this issue will ever be in an active sprint then return the time that it
-  # was first added to that sprint, whether or not the sprint was active at that
-  # time. Although it seems like an odd thing to calculate, it's a reasonable proxy
-  # for 'ready' in cases where the team doesn't have an explicit 'ready' status.
-  # You'd be better off with an explicit 'ready' but sometimes that's not an option.
+  # A sprint the issue was added to: its start (all we care about is whether it started) and the change
+  # that added it.
+  SprintMembership = Data.define(:sprint_id, :sprint_start, :change)
+
+  # Like SprintMembership but also tracks when this issue was added, used while pairing sprint entries
+  # and exits in #sprint_entry_events.
+  TrackedSprint = Data.define(:sprint_id, :sprint_start, :add_time, :change)
+
+  # If this issue is ever in an active sprint, returns the change where it was first added to that
+  # sprint (whether or not the sprint was active at that moment). It's a reasonable proxy for 'ready'
+  # when a team has no explicit 'ready' status -- you'd be better off with one, but sometimes that's
+  # not an option. Only valid for Scrum boards.
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   def first_time_added_to_active_sprint
+    # Why are complexity warnings disabled? Bottom line is that we felt the code would be less readable
+    # if we split it, so it's remaining as one longer method.
+
     unless board.scrum?
       raise 'first_time_added_to_active_sprint() can only be used with Scrum boards: ' \
           "issue=#{key}, board=#{board.inspect}"
     end
-    data_clazz = Struct.new(:sprint_id, :sprint_start, :sprint_stop, :change)
-
     matching_changes = []
-    all_datas = []
+    memberships = []
 
     @changes.each do |change|
       next unless change.sprint?
 
       added_sprint_ids = change.value_id - change.old_value_id
       added_sprint_ids.each do |id|
-        data = data_clazz.new
-        data.sprint_id = id
-        data.change = change
-        data.sprint_start, data.sprint_stop = find_sprint_start_end(sprint_id: id, change: change)
-        all_datas << data
+        sprint_start = find_sprint_start_end(sprint_id: id, change: change).first
+        memberships << SprintMembership.new(sprint_id: id, sprint_start:, change:)
       end
 
       removed_sprint_ids = change.old_value_id - change.value_id
       removed_sprint_ids.each do |id|
-        data = all_datas.find { |d| d.sprint_id == id }
+        membership = memberships.find { |m| m.sprint_id == id }
         # It's possible for an issue to be created inside a sprint and therefore for
         # that add-to-sprint not show in the history.
-        next unless data
+        next unless membership
 
-        all_datas.delete(data)
-        next if data.sprint_start.nil? || data.sprint_start >= change.time
+        memberships.delete(membership)
+        next unless counts_as_sprint_start? membership
+        next if membership.sprint_start >= change.time
 
-        matching_changes << data.change
+        matching_changes << membership.change
       end
     end
 
     # There can't be any more removes so whatever is left is a valid option
     # Now all we care about is if the sprint has started.
-    all_datas.each do |data|
-      matching_changes << data.change if data.sprint_start
+    memberships.each do |membership|
+      matching_changes << membership.change if counts_as_sprint_start? membership
     end
 
     matching_changes.min_by(&:time)
   end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+  # Being added to a sprint only counts as a "start" if that sprint had actually started and the issue
+  # wasn't already done when it did. Joining a sprint you've already finished (e.g. a done issue swept
+  # into a later sprint) is bookkeeping on completed work, not the moment work began.
+  def counts_as_sprint_start? membership
+    return false if membership.sprint_start.nil?
+
+    !in_done_status_at?(membership.sprint_start)
+  end
+
+  # Was the issue sitting in a done-category status at the given moment? Keys off the status category
+  # (not the status name), so a status merely called "Done" that Jira categorises otherwise won't count.
+  def in_done_status_at? time
+    last = status_changes.reverse.find { |change| change.time <= time }
+    return false unless last
+
+    find_or_create_status(id: last.value_id, name: last.value).category.done?
+  end
 
   def find_sprint_start_end sprint_id:, change:
     # There are two different places that sprint data could be found. In theory all
     # sprints would be found in both places. In practice, sometimes what we need is
     # in one or the other but not both.
+    times = sprint_times_from_board(sprint_id) || sprint_times_from_issue(sprint_id, change)
 
-    # First look in the actual sprints json. If any issues are in this sprint then it should
-    # be here.
+    # If both came up empty then the sprint can't be found anywhere, so we pretend that it never
+    # started. Is this guaranteed to be true? No. In theory if all issues were removed from
+    # an active sprint then it would also disappear, even though it had started. Nothing we
+    # can do to detect that edge-case though.
+    times || [nil, nil]
+  end
+
+  # First look in the actual sprints json. If any issues are in this sprint then it should be here.
+  def sprint_times_from_board sprint_id
     sprint = board.sprints.find { |s| s.id == sprint_id }
-    if sprint
-      return [nil, nil] if sprint.future?
+    return nil unless sprint
+    return [nil, nil] if sprint.future?
 
-      return [sprint.start_time, sprint.completed_time]
-    end
+    [sprint.start_time, sprint.completed_time]
+  end
 
-    # Then look at the sprints inside the issue. Even though the field id may be specified,
-    # that custom field may not be present. This happens if it was in that sprint but was
-    # then removed, whether or not that sprint had ever started.
+  # Then look at the sprints inside the issue. Even though the field id may be specified, that custom
+  # field may not be present. This happens if it was in that sprint but was then removed, whether or
+  # not that sprint had ever started.
+  def sprint_times_from_issue sprint_id, change
     sprint_data = raw['fields'][change.field_id]&.find { |sd| sd['id'].to_i == sprint_id }
-    if sprint_data
-      return [nil, nil] if sprint_data['state'] == 'future'
+    return nil unless sprint_data
+    return [nil, nil] if sprint_data['state'] == 'future'
 
-      start = parse_time(sprint_data['startDate'])
-      stop = parse_time(sprint_data['completeDate'])
-      return [start, stop]
-    end
-
-    # If we got this far then the sprint can't be found anywhere, so we pretend that it never
-    # started. Is this guaranteed to be true? No. In theory if all issues were removed from
-    # an active sprint then it would also disappear, even though it had started. Nothing we
-    # can do to detect that edge-case though.
-    [nil, nil]
+    [parse_time(sprint_data['startDate']), parse_time(sprint_data['completeDate'])]
   end
 
   def parse_time text
@@ -339,7 +373,8 @@ class Issue
 
   def created
     # This nil check shouldn't be necessary and yet we've seen one case where it was.
-    parse_time @raw['fields']['created'] if @raw['fields']['created']
+    created_text = raw_fields['created']
+    parse_time created_text if created_text
   end
 
   def time_created
@@ -347,23 +382,23 @@ class Issue
   end
 
   def updated
-    parse_time @raw['fields']['updated']
+    parse_time raw_fields['updated']
   end
 
   def first_resolution
-    @changes.find { |change| change.resolution? }
+    @changes.find(&:resolution?)
   end
 
   def last_resolution
-    @changes.reverse.find { |change| change.resolution? }
+    @changes.reverse.find(&:resolution?)
   end
 
   def assigned_to
-    @raw['fields']['assignee']&.[]('displayName')
+    raw_fields['assignee']&.[]('displayName')
   end
 
   def assigned_to_icon_url
-    @raw['fields']['assignee']&.[]('avatarUrls')&.[]('16x16')
+    raw_fields['assignee']&.[]('avatarUrls')&.[]('16x16')
   end
 
   # Many test failures are simply unreadable because the default inspect on this class goes
@@ -382,197 +417,22 @@ class Issue
   # If the day was stalled for the entire day then it's stalled
   # If there was no activity at all on this day then the last change from the previous day carries over
   def blocked_stalled_by_date date_range:, chart_end_time:, settings: nil
-    results = {}
-    current_date = nil
-    blocked_stalled_changes = blocked_stalled_changes(end_time: chart_end_time, settings: settings)
-    blocked_stalled_changes.each do |change|
-      current_date = change.time.to_date
-
-      winning_change, _last_change = results[current_date]
-      if winning_change.nil? ||
-        change.blocked? ||
-        (change.active? && (winning_change.active? || winning_change.stalled?)) ||
-        (change.stalled? && winning_change.stalled?)
-
-        winning_change = change
-      end
-
-      results[current_date] = [winning_change, change]
-    end
-
-    last_populated_date = nil
-    (results.keys.min..results.keys.max).each do |date|
-      if results.key? date
-        last_populated_date = date
-      else
-        _winner, last = results[last_populated_date]
-        results[date] = [last, last]
-      end
-    end
-    results = results.transform_values(&:first)
-
-    # The requested date range may span outside the actual changes we find in the changelog
-    date_of_first_change = blocked_stalled_changes[0].time.to_date
-    date_of_last_change = blocked_stalled_changes[-1].time.to_date
-    date_range.each do |date|
-      results[date] = blocked_stalled_changes[0] if date < date_of_first_change
-      results[date] = blocked_stalled_changes[-1] if date > date_of_last_change
-    end
-
-    # To make the code simpler, we've been accumulating data for every date. Now remove anything
-    # that isn't in the requested date_range
-    results.select! { |date, _value| date_range.include? date }
-
-    results
+    BlockedStalledByDateBuilder.new(
+      blocked_stalled_changes: blocked_stalled_changes(end_time: chart_end_time, settings: settings),
+      date_range: date_range
+    ).build
   end
 
   def blocked_stalled_changes end_time:, settings: nil
     settings ||= @board.project_config.settings
-
-    blocked_statuses = settings['blocked_statuses']
-    stalled_statuses = settings['stalled_statuses']
-
-    blocked_link_texts = settings['blocked_link_text']
-    stalled_threshold = settings['stalled_threshold_days']
-    flagged_means_blocked = !!settings['flagged_means_blocked'] # rubocop:disable Style/DoubleNegation
-
-    blocking_issue_keys = []
-
-    result = []
-    previous_was_active = false # Must start as false so that the creation will insert an :active
-    previous_change_time = created
-
-    blocking_status = nil
-    blocking_is_blocked = false
-    flag = nil
-    flag_reason = nil
-
-    # This mock change is to force the writing of one last entry at the end of the time range.
-    # By doing this, we're able to eliminate a lot of duplicated code in charts.
-    mock_change = ChangeItem.new time: end_time, artificial: true, raw: { 'field' => '' }, author_raw: nil
-
-    (changes + [mock_change]).each do |change|
-      previous_was_active = false if check_for_stalled(
-        change_time: change.time,
-        previous_change_time: previous_change_time,
-        stalled_threshold: stalled_threshold,
-        blocking_stalled_changes: result
-      )
-
-      if change.flagged? && flagged_means_blocked
-        flag, flag_reason = blocked_stalled_changes_flag_logic change
-      elsif change.status?
-        blocking_status = nil
-        blocking_is_blocked = false
-        if blocked_statuses.find_by_id(change.value_id)
-          blocking_status = change.value
-          blocking_is_blocked = true
-        elsif stalled_statuses.find_by_id(change.value_id)
-          blocking_status = change.value
-        end
-      elsif change.link?
-        # Example: "This issue is satisfied by ANON-30465"
-        unless /^This (?<_>issue|work item) (?<link_text>.+) (?<issue_key>.+)$/ =~ (change.value || change.old_value)
-          puts "Issue(#{key}) Can't parse link text: #{change.value || change.old_value}"
-          next
-        end
-
-        if blocked_link_texts.include? link_text
-          if change.value
-            blocking_issue_keys << issue_key
-          else
-            blocking_issue_keys.delete issue_key
-          end
-        end
-      end
-
-      new_change = BlockedStalledChange.new(
-        flagged: flag,
-        flag_reason: flag_reason,
-        status: blocking_status,
-        status_is_blocking: blocking_status.nil? || blocking_is_blocked,
-        blocking_issue_keys: (blocking_issue_keys.empty? ? nil : blocking_issue_keys.dup),
-        time: change.time
-      )
-
-      # We don't want to dump two actives in a row as that would just be noise. Unless this is
-      # the mock change, which we always want to dump
-      result << new_change if !new_change.active? || !previous_was_active || change == mock_change
-
-      previous_was_active = new_change.active?
-      previous_change_time = change.time
-    end
-
-    if result.size >= 2
-      # The existence of the mock entry will mess with the stalled count as it will wake everything
-      # back up. This hack will clean up appropriately.
-      hack = result.pop
-      result << BlockedStalledChange.new(
-        flagged: hack.flag,
-        flag_reason: hack.flag_reason,
-        status: hack.status,
-        status_is_blocking: hack.status_is_blocking,
-        blocking_issue_keys: hack.blocking_issue_keys,
-        time: hack.time,
-        stalled_days: result[-1].stalled_days
-      )
-    end
-
-    result
-  end
-
-  def blocked_stalled_changes_flag_logic change
-    flag = change.value
-    flag = nil if change.value == ''
-    if flag
-      # When the user is adding a comment to explain why a flag was set, the flag is set immediately
-      # and the comment is inserted after the user hits enter, which means that there is some time
-      # gap. If a comment happened shortly after the flag was set, we assume they're linked. This
-      # won't always be true and so there will be false positives, but it's a reasonable assumption.
-      max_seconds_between_flag_and_comment = 30
-      comment_change = changes.find do |c|
-        c.comment? && c.time >= change.time && (c.time - change.time) <= max_seconds_between_flag_and_comment
-      end
-      flag_reason = comment_change && @board.project_config.atlassian_document_format.to_text(comment_change.value)
-      # Newer Jira instances may add this extra text but older instances did not. Strip it out if found.
-      flag_reason = flag_reason&.sub(/\A:flag_on: Flag added\s*/m, '')&.strip
-      flag_reason = nil if flag_reason&.empty?
-    else
-      flag_reason = nil
-    end
-    [flag, flag_reason]
-  end
-
-  def check_for_stalled change_time:, previous_change_time:, stalled_threshold:, blocking_stalled_changes:
-    stalled_threshold_seconds = stalled_threshold * 60 * 60 * 24
-
-    # The most common case will be nothing to split so quick escape.
-    return false if (change_time - previous_change_time).to_i < stalled_threshold_seconds
-
-    # If the last identified change was blocked then it doesn't matter now long we've waited, we're still blocked.
-    return false if blocking_stalled_changes[-1]&.blocked?
-
-    list = [previous_change_time..change_time]
-    all_subtask_activity_times.each do |time|
-      matching_range = list.find { |range| time >= range.begin && time <= range.end }
-      next unless matching_range
-
-      list.delete matching_range
-      list << ((matching_range.begin)..time)
-      list << (time..(matching_range.end))
-    end
-
-    inserted_stalled = false
-
-    list.sort_by(&:begin).each do |range|
-      seconds = (range.end - range.begin).to_i
-      next if seconds < stalled_threshold_seconds
-
-      an_hour_later = range.begin + (60 * 60)
-      blocking_stalled_changes << BlockedStalledChange.new(stalled_days: seconds / (24 * 60 * 60), time: an_hour_later)
-      inserted_stalled = true
-    end
-    inserted_stalled
+    BlockedStalledChangeStreamBuilder.new(
+      changes: changes,
+      settings: settings,
+      created: created,
+      key: key,
+      subtask_activity_times: all_subtask_activity_times,
+      atlassian_document_format: @board.project_config.atlassian_document_format
+    ).build(end_time: end_time)
   end
 
   # return [number of active seconds, total seconds] that this issue had up to the end_time.
@@ -581,37 +441,13 @@ class Issue
     issue_start, issue_stop = started_stopped_times
     return [0.0, 0.0] if !issue_start || issue_start > end_time
 
-    value_add_time = 0.0
+    # Nothing after the issue finishes counts, so cap the window before we build the stream.
     end_time = issue_stop if issue_stop && issue_stop < end_time
-
-    active_start = nil
-    blocked_stalled_changes(end_time: end_time, settings: settings).each_with_index do |change, index|
-      break if change.time > end_time
-
-      if index.zero?
-        active_start = change.time if change.active?
-        next
-      end
-
-      # Already active and we just got another active.
-      next if active_start && change.active?
-
-      if change.active?
-        active_start = change.time
-      elsif active_start && change.time >= issue_start
-        # Not active now but we have been. Record the active time.
-        change_delta = change.time - [issue_start, active_start].max
-        value_add_time += change_delta
-        active_start = nil
-      end
-    end
-
-    if active_start
-      change_delta = end_time - [issue_start, active_start].max
-      value_add_time += change_delta if change_delta.positive?
-    end
-
-    [value_add_time, end_time - issue_start]
+    FlowEfficiencyCalculator.new(
+      blocked_stalled_changes: blocked_stalled_changes(end_time: end_time, settings: settings),
+      issue_start: issue_start,
+      end_time: end_time
+    ).calculate
   end
 
   def all_subtask_activity_times
@@ -631,26 +467,30 @@ class Issue
   end
 
   def expedited_on_date? date
-    expedited_start = nil
     return false unless @board&.project_config
 
+    expedited_ranges.any? { |range| range.cover?(date) }
+  end
+
+  # The date ranges during which this issue sat at an expedited priority. A range that never closes
+  # (the issue was never de-prioritised) is endless.
+  def expedited_ranges
     expedited_names = @board.project_config.settings['expedited_priority_names']
+    ranges = []
+    started_on = nil
 
     changes.each do |change|
       next unless change.priority?
 
       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).cover?(date)
-
-        expedited_start = nil
+        started_on ||= change.time.to_date
+      elsif started_on
+        ranges << (started_on..change.time.to_date)
+        started_on = nil
       end
     end
-
-    return false if expedited_start.nil?
-
-    expedited_start <= date
+    ranges << (started_on..) if started_on
+    ranges
   end
 
   # Return the last time there was any activity on this ticket. Starting from "now" and going backwards
@@ -671,7 +511,7 @@ class Issue
 
   def issue_links
     if @issue_links.nil?
-      @issue_links = @raw['fields']['issuelinks']&.collect do |issue_link|
+      @issue_links = raw_fields['issuelinks']&.collect do |issue_link|
         IssueLink.new origin: self, raw: issue_link
       end || []
     end
@@ -680,7 +520,7 @@ class Issue
 
   def fix_versions
     if @fix_versions.nil?
-      @fix_versions = @raw['fields']['fixVersions']&.collect do |fix_version|
+      @fix_versions = raw_fields['fixVersions']&.collect do |fix_version|
         FixVersion.new fix_version
       end || []
     end
@@ -695,34 +535,31 @@ class Issue
     # Although Atlassian is trying to standardize on one way to determine the parent, today it's a mess.
     # We try a variety of ways to get the parent and hopefully one of them will work. See this link:
     # https://community.developer.atlassian.com/t/deprecation-of-the-epic-link-parent-link-and-other-related-fields-in-rest-apis-and-webhooks/54048
+    fields = raw_fields
 
-    fields = @raw['fields']
-
-    # At some point in the future, this will be the only way to retrieve the parent so we try this first.
-    parent = fields['parent']&.[]('key')
-
-    # The epic field
-    parent = fields['epic']&.[]('key') if parent.nil?
+    # The 'parent' field will eventually be the only way; the 'epic' field is the older form. Failing
+    # both, the parent link may be stored in a custom field.
+    parent = fields['parent']&.[]('key') || fields['epic']&.[]('key')
+    parent ||= parent_from_custom_fields(fields, project_config) if project_config
+    parent
+  end
 
-    # Otherwise the parent link will be stored in one of the custom fields. We've seen different custom fields
-    # used for parent_link vs epic_link so we have to support more than one.
-    if parent.nil? && project_config
-      custom_field_names = project_config.settings['customfield_parent_links']
-      custom_field_names = [custom_field_names] if custom_field_names.is_a? String
+  def parent_from_custom_fields fields, project_config
+    # We've seen different custom fields used for parent_link vs epic_link, so we try each configured
+    # one until we find a value that looks like an issue key.
+    custom_field_names = project_config.settings['customfield_parent_links']
+    custom_field_names = [custom_field_names] if custom_field_names.is_a? String
 
-      custom_field_names&.each do |field_name|
-        parent = fields[field_name]
-        next if parent.nil?
-        break if looks_like_issue_key? parent
+    custom_field_names&.each do |field_name|
+      parent = fields[field_name]
+      next if parent.nil?
+      return parent if looks_like_issue_key? parent
 
-        project_config.file_system.log(
-          "Custom field #{field_name.inspect} should point to a parent id but found #{parent.inspect}"
-        )
-        parent = nil
-      end
+      project_config.file_system.log(
+        "Custom field #{field_name.inspect} should point to a parent id but found #{parent.inspect}"
+      )
     end
-
-    parent
+    nil
   end
 
   def in_initial_query?
@@ -746,17 +583,19 @@ class Issue
   def discard_changes_before cutoff_time
     rejected_any = false
     @changes.reject! do |change|
-      reject = change.status? && change.time <= cutoff_time && change.artificial? == false
-      if reject
-        (@discarded_changes ||= []) << change
-        rejected_any = true
-      end
-      reject
+      next false unless discardable_before? change, cutoff_time
+
+      (@discarded_changes ||= []) << change
+      rejected_any = true
     end
 
     (@discarded_change_times ||= []) << cutoff_time if rejected_any
   end
 
+  def discardable_before? change, cutoff_time
+    change.status? && change.time <= cutoff_time && change.artificial? == false
+  end
+
   def dump
     IssuePrinter.new(self).to_s
   end
@@ -780,7 +619,7 @@ class Issue
   end
 
   def status_changes
-    @changes.select { |change| change.status? }
+    @changes.select(&:status?)
   end
 
   def status_resolution_at_done
@@ -807,7 +646,7 @@ class Issue
     changes.each do |change|
       next unless change.sprint?
 
-      sprint_ids << change.raw['to'].split(/\s*,\s*/).collect { |id| id.to_i }
+      sprint_ids << change.raw['to'].split(/\s*,\s*/).collect(&:to_i)
     end
     sprint_ids.flatten!
 
@@ -815,17 +654,13 @@ class Issue
   end
 
   def started_sprints
-    sprints.reject { |sprint| sprint.future? }
+    sprints.reject(&:future?)
   end
 
   def compact_text text, max: 60
     return '' if text.nil?
 
-    text = if text.is_a? Hash
-             @board.project_config.atlassian_document_format.to_text(text)
-           else
-             text
-           end
+    text = @board.project_config.atlassian_document_format.to_text(text) if text.is_a? Hash
     text = text.gsub(/\s+/, ' ').strip
     text = "#{text[0...max]}..." if text.length > max
     text
@@ -836,36 +671,47 @@ class Issue
   # Returns [[effective_time, change_item]] for each moment the issue entered an active sprint.
   # Skips sprints that were removed before they activated.
   def sprint_entry_events
-    data_clazz = Struct.new(:sprint_id, :sprint_start, :add_time, :change)
     events = []
     in_sprint = []
 
     @changes.each do |change|
       next unless change.sprint?
 
-      (change.value_id - change.old_value_id).each do |sprint_id|
-        sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
-        in_sprint << data_clazz.new(sprint_id, sprint_start, change.time, change) if sprint_start
-      end
-
-      (change.old_value_id - change.value_id).each do |sprint_id|
-        data = in_sprint.find { |d| d.sprint_id == sprint_id }
-        next unless data
+      add_tracked_sprints(in_sprint, change)
+      close_tracked_sprints(in_sprint, change, events)
+    end
 
-        in_sprint.delete(data)
-        next if data.sprint_start >= change.time # sprint hadn't activated before removal
+    # Anything still tracked at the end never left, so its entry is the moment it started (or was added).
+    in_sprint.each { |tracked| events << sprint_entry_event_for(tracked) }
+    events
+  end
 
-        effective_time = [data.add_time, data.sprint_start].max
-        events << [effective_time, sprint_change_at(effective_time, data.change)]
-      end
+  # Records each sprint this change newly joined, but only those we know eventually started.
+  def add_tracked_sprints in_sprint, change
+    (change.value_id - change.old_value_id).each do |sprint_id|
+      sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
+      in_sprint << TrackedSprint.new(sprint_id:, sprint_start:, add_time: change.time, change:) if sprint_start
     end
+  end
+
+  # Emits an entry for each sprint this change left, unless it was removed before ever activating.
+  def close_tracked_sprints in_sprint, change, events
+    (change.old_value_id - change.value_id).each do |sprint_id|
+      tracked = in_sprint.find { |candidate| candidate.sprint_id == sprint_id }
+      next unless tracked
 
-    in_sprint.each do |data|
-      effective_time = [data.add_time, data.sprint_start].max
-      events << [effective_time, sprint_change_at(effective_time, data.change)]
+      in_sprint.delete(tracked)
+      next if tracked.sprint_start >= change.time # sprint hadn't activated before removal
+
+      events << sprint_entry_event_for(tracked)
     end
+  end
 
-    events
+  # The moment the issue was effectively in an active sprint - the later of when it was added and when
+  # the sprint started - paired with the change that best represents that moment.
+  def sprint_entry_event_for tracked
+    effective_time = [tracked.add_time, tracked.sprint_start].max
+    [effective_time, sprint_change_at(effective_time, tracked.change)]
   end
 
   def sprint_change_at effective_time, change
@@ -885,15 +731,21 @@ class Issue
       break if change.time > time
       next unless change.sprint?
 
-      (change.value_id - change.old_value_id).each do |sprint_id|
-        sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
-        active_ids << sprint_id if sprint_start && sprint_start <= time
-      end
-      (change.old_value_id - change.value_id).each { |id| active_ids.delete(id) }
+      apply_sprint_membership_change(active_ids, change, time)
     end
     active_ids.any?
   end
 
+  # Adds the sprints newly joined by this change (only if they had already started by `time`) and
+  # removes the ones it left, mutating active_ids in place.
+  def apply_sprint_membership_change active_ids, change, time
+    (change.value_id - change.old_value_id).each do |sprint_id|
+      sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
+      active_ids << sprint_id if sprint_start && sprint_start <= time
+    end
+    (change.old_value_id - change.value_id).each { |id| active_ids.delete(id) }
+  end
+
   def in_visible_status_at? time, visible_status_ids
     last = status_changes.reverse.find { |c| c.time <= time }
     last && visible_status_ids.include?(last.value_id)
@@ -904,30 +756,40 @@ class Issue
       created = parse_time(history['created'])
 
       history['items']&.each do |item|
-        if item['field'] == 'status' && item['to'].nil?
-          to_name = item['toString']
-          matches = board.possible_statuses.find_all_by_name(to_name)
-          guessed_id, id_note = if matches.length == 1
-            [matches.first.id.to_s, "Guessed id #{matches.first.id} from status name."]
-          elsif matches.length > 1
-            ['0', "Multiple statuses named #{to_name.inspect} exist (ids: #{matches.map(&:id).join(', ')}); cannot disambiguate. Using id 0."]
-          else
-            ['0', "No known status named #{to_name.inspect}. Using id 0."]
-          end
-          board.project_config.file_system.warning(
-            "Issue #{key} has a status change without a 'to' id " \
-            "(from #{item['fromString'].inspect} to #{to_name.inspect}). #{id_note}"
-          )
-          item = item.merge('to' => guessed_id)
-        end
-
+        item = backfill_missing_status_id(item) if item['field'] == 'status' && item['to'].nil?
         @changes << ChangeItem.new(raw: item, time: created, author_raw: history['author'])
       end
     end
   end
 
+  # Jira sometimes reports a status change with a name but no id. Guess the id from the name (when we
+  # can) and return a copy of the item with a 'to' filled in, logging what we did.
+  def backfill_missing_status_id item
+    to_name = item['toString']
+    matches = board.possible_statuses.find_all_by_name(to_name)
+    guessed_id, id_note = guess_status_id(to_name, matches)
+    board.project_config.file_system.warning(
+      "Issue #{key} has a status change without a 'to' id " \
+      "(from #{item['fromString'].inspect} to #{to_name.inspect}). #{id_note}"
+    )
+    item.merge('to' => guessed_id)
+  end
+
+  # Returns [id_as_string, explanation]. A single name match gives that id; anything else falls back to
+  # id 0 because we can't safely disambiguate.
+  def guess_status_id to_name, matches
+    if matches.length == 1
+      [matches.first.id.to_s, "Guessed id #{matches.first.id} from status name."]
+    elsif matches.length > 1
+      ['0', "Multiple statuses named #{to_name.inspect} exist " \
+            "(ids: #{matches.map(&:id).join(', ')}); cannot disambiguate. Using id 0."]
+    else
+      ['0', "No known status named #{to_name.inspect}. Using id 0."]
+    end
+  end
+
   def load_comments_into_changes
-    @raw['fields']['comment']['comments']&.each do |comment|
+    raw_fields['comment']['comments']&.each do |comment|
       raw = comment.merge({
         'field' => 'comment',
         'to' => comment['id'],
@@ -956,16 +818,16 @@ class Issue
     first_status_id = nil
 
     # There won't be a created timestamp in cases where this was a linked issue
-    return unless @raw['fields']['created']
+    return unless raw_fields['created']
 
-    created_time = parse_time @raw['fields']['created']
+    created_time = parse_time raw_fields['created']
     first_change = @changes.find { |change| change.field == field_name }
     if first_change.nil?
       # There have been no changes of this type yet so we have to look at the current one
-      return nil unless @raw['fields'][field_name]
+      return nil unless raw_fields[field_name]
 
-      first_status = @raw['fields'][field_name]['name']
-      first_status_id = @raw['fields'][field_name]['id'].to_i
+      first_status = raw_fields[field_name]['name']
+      first_status_id = raw_fields[field_name]['id'].to_i
     else
       # Otherwise, we look at what the first one had changed away from.
       first_status = first_change.old_value
@@ -975,7 +837,7 @@ class Issue
       first_status_id = first_change.old_value_id || 0
     end
 
-    creator = raw['fields']['creator']
+    creator = raw_fields['creator']
     ChangeItem.new time: created_time, artificial: true, author_raw: creator, raw: {
       'field' => field_name,
       'to' => first_status_id,
@@ -983,6 +845,45 @@ class Issue
     }
   end
 
+  # Jira never records an issue's *initial* sprint membership as a changelog transition, so an issue
+  # created directly inside a sprint (and never moved out) has no Sprint change at all, and one whose
+  # first recorded change already lists the sprint in its 'from' looks like it entered at that later
+  # moment. Reconstruct that initial membership as an artificial change at creation time, mirroring how
+  # we fabricate the initial status and priority. Returns nil when the issue started in no sprints.
+  def fabricate_sprint_change
+    return unless raw_fields['created']
+
+    first_sprint_change = @changes.find(&:sprint?)
+    initial_sprint_ids = first_sprint_change ? first_sprint_change.old_value_id : current_sprint_ids
+    return if initial_sprint_ids.empty?
+
+    ChangeItem.new(
+      time: parse_time(raw_fields['created']), artificial: true, author_raw: raw_fields['creator'],
+      raw: {
+        'field' => 'Sprint',
+        'fieldId' => first_sprint_change&.field_id || sprint_field_id,
+        'to' => initial_sprint_ids.join(', '),
+        'toString' => 'Sprint'
+      }
+    )
+  end
+
+  # The Sprint custom field id varies by Jira instance, so we find it by shape: its value is a list of
+  # sprint objects, each of which carries a boardId. Returns nil when the issue is in no sprints.
+  def sprint_field_id
+    field = raw_fields.find do |_field_id, value|
+      value.is_a?(Array) && value.first.is_a?(Hash) && value.first.key?('boardId')
+    end
+    field&.first
+  end
+
+  def current_sprint_ids
+    field_id = sprint_field_id
+    return [] unless field_id
+
+    raw_fields[field_id].filter_map { |sprint| sprint['id']&.to_i }
+  end
+
   def find_status_category_ids_by_names category_names
     category_names.filter_map do |name|
       list = board.possible_statuses.find_all_categories_by_name name