jirametrics 2.31 → 3.0

data/lib/jirametrics/atlassian_document_format.rb

@@ -12,7 +12,9 @@ class AtlassianDocumentFormat
     if input.is_a? String
       input
         .gsub(/{color:(#\w{6})}([^{]+){color}/, '<span style="color: \1">\2</span>') # Colours
+        # rubocop:disable Style/PerlBackrefs -- in a gsub block $1 reads cleaner than Regexp.last_match[:...]
         .gsub(/\[~accountid:([^\]]+)\]/) { expand_account_id $1 } # Tagged people
+        # rubocop:enable Style/PerlBackrefs
         .gsub(/\[([^|]+)\|(https?[^\]]+)\]/, '<a href="\2">\1</a>') # URLs
         .gsub("\n", '<br />')
     elsif input&.[]('content')
@@ -35,7 +37,11 @@ class AtlassianDocumentFormat
 
   # ADF is Atlassian Document Format
   # https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
-  def adf_node_to_html node # rubocop:disable Metrics/CyclomaticComplexity
+  #
+  # Flat node-type dispatch: ~25 trivial branches mapping an ADF node type to its [prefix, suffix]
+  # pair (adf_node_render does the recursion). The complexity here is breadth, not depth — a lookup
+  # table would only trade a scannable case for a hash plus indirection, so we keep the case.
+  def adf_node_to_html node # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
     adf_node_render(node) do |n|
       node_attrs = n['attrs']
       case n['type']
@@ -74,20 +80,21 @@ class AtlassianDocumentFormat
       when 'taskItem'
         state = node_attrs['state'] == 'TODO' ? '☐' : '☑'
         ["<li>#{state} ", '</li>']
-      when 'taskList'                  then ["<ul class='taskList'>", '</ul>']
+      when 'taskList' then ["<ul class='taskList'>", '</ul>']
       else
         ["<p>Unparseable section: #{n['type']}</p>", nil]
       end
     end
   end
 
+  # Flat node-type dispatch, same reasoning as adf_node_to_html: breadth, not depth. Kept as a case.
   def adf_node_to_text node # rubocop:disable Metrics/CyclomaticComplexity
     adf_node_render(node) do |n|
       node_attrs = n['attrs']
       case n['type']
       when 'blockquote', 'bulletList', 'codeBlock',
            'mediaSingle', 'mediaGroup',
-           'orderedList', 'table', 'taskList'  then ['', nil]
+           'orderedList', 'table', 'taskList' then ['', nil]
       when 'date'
         [Time.at(node_attrs['timestamp'].to_i / 1000, in: @timezone_offset).to_date.to_s, nil]
       when 'decisionItem'              then ['- ', "\n"]
@@ -151,7 +158,7 @@ class AtlassianDocumentFormat
   private
 
   def adf_node_render node, &render_node
-    prefix, suffix = render_node.call(node)
+    prefix, suffix = yield(node)
     result = +(prefix || '')
     node['content']&.each { |child| result << adf_node_render(child, &render_node) }
     result << suffix if suffix

data/lib/jirametrics/blocked_stalled_by_date_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Rolls a stream of BlockedStalledChange entries up into a single winning entry per date across
+# the requested date range. It's handed the already-computed stream so it never reaches back
+# through the issue's collaborators.
+class BlockedStalledByDateBuilder
+  def initialize blocked_stalled_changes:, date_range:
+    @blocked_stalled_changes = blocked_stalled_changes
+    @date_range = date_range
+  end
+
+  def build
+    results = winners_and_last_by_date
+    fill_gaps results
+    results = results.transform_values(&:first)
+    extrapolate_across_range results
+
+    # We've been accumulating data for every date to keep the code simple. Now drop anything
+    # that isn't in the requested date_range.
+    results.select! { |date, _value| @date_range.include? date }
+    results
+  end
+
+  # For each date we track both the winning change (the one that best represents the day) and the
+  # last change seen (used to carry state forward into days that had no changes of their own).
+  def winners_and_last_by_date
+    results = {}
+    @blocked_stalled_changes.each do |change|
+      date = change.time.to_date
+      winning_change, = results[date]
+      winning_change = change if winning_change.nil? || wins_the_day?(change, winning_change)
+      results[date] = [winning_change, change]
+    end
+    results
+  end
+
+  def wins_the_day? change, winning_change
+    change.blocked? ||
+      (change.active? && (winning_change.active? || winning_change.stalled?)) ||
+      (change.stalled? && winning_change.stalled?)
+  end
+
+  def fill_gaps results
+    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
+  end
+
+  def extrapolate_across_range results
+    # 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
+  end
+end

data/lib/jirametrics/blocked_stalled_change.rb

@@ -4,6 +4,7 @@ require 'jirametrics/value_equality'
 
 class BlockedStalledChange
   include ValueEquality
+
   attr_reader :time, :blocking_issue_keys, :flag, :flag_reason, :status, :stalled_days, :status_is_blocking
 
   def initialize time:, flagged: nil, flag_reason: nil, status: nil, status_is_blocking: true,
@@ -24,7 +25,10 @@ class BlockedStalledChange
   def blocked_by_status? = !!(@status && @status_is_blocking)
   def stalled_by_status? = !!(@status && !@status_is_blocking)
 
-  def reasons
+  def reasons # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # A flat list of why an item is blocked or stalled: each branch is a single guarded append.
+    # Pulling these apart into helpers would scatter the story across single-use methods without
+    # reading any clearer, so we keep it whole.
     result = []
     if blocked?
       result << (@flag_reason ? "Blocked by flag: #{@flag_reason}" : 'Blocked by flag') if @flag

data/lib/jirametrics/blocked_stalled_change_stream_builder.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# Builds the time-ordered stream of BlockedStalledChange entries for a single issue.
+# Everything it needs is passed in explicitly (changes, settings, and a few resolved values)
+# so it never reaches back through the issue's collaborators.
+class BlockedStalledChangeStreamBuilder
+  # Mutable state threaded through the change loop as we walk the issue's history. Each branch
+  # only overwrites the fields it owns, so a flag/status/link value persists until the next change
+  # of that kind replaces it.
+  BlockingState = Struct.new(
+    :flag, :flag_reason, :status, :is_blocked, :blocking_issue_keys, keyword_init: true
+  )
+
+  def initialize changes:, settings:, created:, key:, subtask_activity_times:, atlassian_document_format:
+    @changes = changes
+    @settings = settings
+    @created = created
+    @key = key
+    @subtask_activity_times = subtask_activity_times
+    @atlassian_document_format = atlassian_document_format
+  end
+
+  def build end_time:
+    result = []
+    state = BlockingState.new(flag: nil, flag_reason: nil, status: nil, is_blocked: false, blocking_issue_keys: [])
+    previous_was_active = false # Must start as false so that the creation will insert an :active
+    previous_change_time = @created
+
+    # 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: @settings['stalled_threshold_days'],
+        blocking_stalled_changes: result
+      )
+
+      update_blocking_state state, change
+
+      new_change = new_blocked_stalled_change state, 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 record_change? new_change, previous_was_active, change, mock_change
+
+      previous_was_active = new_change.active?
+      previous_change_time = change.time
+    end
+
+    finalize_stalled_tail result
+    result
+  end
+
+  def update_blocking_state state, change
+    if change.flagged? && flagged_means_blocked?
+      state.flag, state.flag_reason = flag_logic change
+    elsif change.status?
+      state.status, state.is_blocked = status_change change
+    elsif change.link?
+      apply_link_change change, state.blocking_issue_keys
+    end
+  end
+
+  def flagged_means_blocked?
+    !!@settings['flagged_means_blocked']
+  end
+
+  def new_blocked_stalled_change state, time
+    BlockedStalledChange.new(
+      flagged: state.flag,
+      flag_reason: state.flag_reason,
+      status: state.status,
+      status_is_blocking: state.status.nil? || state.is_blocked,
+      blocking_issue_keys: (state.blocking_issue_keys.empty? ? nil : state.blocking_issue_keys.dup),
+      time: time
+    )
+  end
+
+  def record_change? candidate, previous_was_active, change, mock_change
+    !candidate.active? || !previous_was_active || change == mock_change
+  end
+
+  def status_change change
+    if @settings['blocked_statuses'].find_by_id(change.value_id)
+      [change.value, true]
+    elsif @settings['stalled_statuses'].find_by_id(change.value_id)
+      [change.value, false]
+    else
+      [nil, false]
+    end
+  end
+
+  def apply_link_change change, blocking_issue_keys
+    link_value = change.value || change.old_value
+    # Example: "This issue is satisfied by ANON-30465"
+    unless /^This (?<_>issue|work item) (?<link_text>.+) (?<issue_key>.+)$/ =~ link_value
+      puts "Issue(#{@key}) Can't parse link text: #{link_value}"
+      return
+    end
+
+    return unless @settings['blocked_link_text'].include? link_text
+
+    if change.value
+      blocking_issue_keys << issue_key
+    else
+      blocking_issue_keys.delete issue_key
+    end
+  end
+
+  def flag_logic change
+    flag = change.value
+    flag = nil if change.value == ''
+    [flag, flag ? flag_reason_from_comment(change) : nil]
+  end
+
+  def flag_reason_from_comment change
+    comment_change = comment_near change.time
+    flag_reason = comment_change && @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 && flag_reason.empty?
+    flag_reason
+  end
+
+  def comment_near flag_time
+    # 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
+    @changes.find do |c|
+      c.comment? && c.time >= flag_time && (c.time - flag_time) <= max_seconds_between_flag_and_comment
+    end
+  end
+
+  def finalize_stalled_tail result
+    return unless 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
+
+  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?
+
+    ranges = split_range_by_subtask_activity previous_change_time..change_time
+    insert_stalled_changes ranges, stalled_threshold_seconds, blocking_stalled_changes
+  end
+
+  def split_range_by_subtask_activity initial_range
+    list = [initial_range]
+    @subtask_activity_times.each do |time|
+      matching_range = list.find { |range| time.between?(range.begin, range.end) }
+      next unless matching_range
+
+      list.delete matching_range
+      list << (matching_range.begin..time)
+      list << (time..matching_range.end)
+    end
+    list
+  end
+
+  def insert_stalled_changes ranges, stalled_threshold_seconds, blocking_stalled_changes
+    inserted_stalled = false
+    ranges.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
+  end
+end

data/lib/jirametrics/board.rb

@@ -35,9 +35,9 @@ class Board
   end
 
   def server_url_prefix
-    raise "Cannot parse self: #{@raw['self'].inspect}" unless @raw['self'] =~ /^(https?:\/\/.+)\/rest\//
+    raise "Cannot parse self: #{@raw['self'].inspect}" unless %r{^(?<prefix>https?://.+)/rest/} =~ @raw['self']
 
-    $1
+    prefix
   end
 
   def url
@@ -59,20 +59,34 @@ class Board
       status_ids += column.status_ids if found_it
     end
 
-    unless found_it
-      column_names = @visible_columns.collect { |c| c.name.inspect }.join(', ')
-      raise "No visible column with name: #{column_name.inspect} Possible options are: #{column_names}"
-    end
+    raise column_not_found_message(column_name) unless found_it
+
     status_ids
   end
 
+  # Column-name matching is case-sensitive, so a config asking for "Done" against a board whose column
+  # is "DONE" fails -- and that's the mistake people actually make. When only the case differs, name the
+  # likely intended column outright instead of making the reader spot it in the list themselves.
+  def column_not_found_message column_name
+    names = @visible_columns.collect(&:name)
+    suggestion = names.find { |name| name.casecmp?(column_name) }
+    unless suggestion
+      return "No visible column named #{column_name.inspect}. " \
+        "The visible columns are: #{names.collect(&:inspect).join(', ')}."
+    end
+
+    others = (names - [suggestion]).collect(&:inspect).join(', ')
+    "You specified #{column_name.inspect} but probably meant #{suggestion.inspect}. Column names are " \
+      "case-sensitive. If that's not it, the other visible columns are: #{others}."
+  end
+
   def board_type = raw['type']
 
   def scrum?
     return true if board_type == 'scrum'
     return false unless board_type == 'simple'
 
-    has_sprints_feature?
+    sprints_feature?
   end
 
   def kanban?
@@ -83,10 +97,10 @@ class Board
   end
 
   def team_managed_kanban?
-    board_type == 'simple' && !has_sprints_feature?
+    board_type == 'simple' && !sprints_feature?
   end
 
-  def has_sprints_feature?
+  def sprints_feature?
     @features.any? { |f| f.name == 'jsw.agility.sprints' && f.enabled? }
   end
 

data/lib/jirametrics/board_config.rb

@@ -29,11 +29,4 @@ class BoardConfig
       settings: project_config.settings
     )
   end
-
-  def expedited_priority_names *priority_names
-    project_config.exporter.file_system.deprecated(
-      date: '2024-09-15', message: 'Expedited priority names are now specified in settings'
-    )
-    @project_config.settings['expedited_priority_names'] = priority_names
-  end
 end

data/lib/jirametrics/board_movement_calculator.rb

@@ -10,19 +10,16 @@ class BoardMovementCalculator
   end
 
   def moves_backwards? issue
-    started, stopped = issue.started_stopped_times
+    started, = issue.started_stopped_times
     return false unless started
 
-    previous_column = nil
-    issue.status_changes.each do |change|
-      column = board.visible_columns.index { |c| c.status_ids.include?(change.value_id) }
-      next if change.time < started
-      next if column.nil? # It disappeared from the board for a bit
-      return true if previous_column && column && column < previous_column
+    # filter_map drops any status that isn't on a visible column (it disappeared from the board for a bit),
+    # so a dip either side of that gap is still seen as consecutive columns.
+    columns = issue.status_changes
+      .select { |change| change.time >= started }
+      .filter_map { |change| board.visible_columns.index { |c| c.status_ids.include?(change.value_id) } }
 
-      previous_column = column
-    end
-    false
+    columns.each_cons(2).any? { |previous, current| current < previous }
   end
 
   def stacked_age_data_for percentages:
@@ -63,7 +60,13 @@ class BoardMovementCalculator
     data
   end
 
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   def ages_of_issues_when_leaving_column column_index:, today:
+    # Why are complexity warnings disabled? This is an inherently sequential run of guard clauses
+    # feeding a single age calculation. Pulling pieces out (the skip rules, the end-date case) would
+    # scatter the linear "compute the column times -> apply the skip rules -> pick the end date -> age"
+    # story across single-use methods and read worse, so we keep it whole.
+
     this_column = board.visible_columns[column_index]
     next_column = board.visible_columns[column_index + 1]
 
@@ -84,20 +87,20 @@ class BoardMovementCalculator
       # Skip if it was already done by the time it got to this column or it became done when it got to this column
       next if issue_done && issue_done <= this_column_start
 
-      end_date = case # rubocop:disable Style/EmptyCaseCondition
-      when next_column_start.nil?
-        # If this is the last column then base age against today
-        today
-      when issue_done && issue_done < next_column_start
-        # it completed while in this column
-        issue_done.to_date
-      else
-        # It passed through this whole column
-        next_column_start.to_date
-      end
+      end_date = if next_column_start.nil?
+                   # If this is the last column then base age against today
+                   today
+                 elsif issue_done && issue_done < next_column_start
+                   # it completed while in this column
+                   issue_done.to_date
+                 else
+                   # It passed through this whole column
+                   next_column_start.to_date
+                 end
       (end_date - issue_start.to_date).to_i + 1
     end.sort
   end
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   # Figure out what column this is issue is currently in and what time it entered that column. We need this for
   # aging and forecasting purposes

data/lib/jirametrics/cfd_data_builder.rb

@@ -29,65 +29,67 @@ class CfdDataBuilder
     map
   end
 
-  # Returns { hwm_timeline: [[date, hwm_value], ...], correction_windows: [...] }
+  # Tracks an issue's furthest progress (the high water mark) and, whenever it slips behind that mark,
+  # the correction window that stays open until it recovers. Mutated in place as we walk the changes.
+  CorrectionState = Struct.new(
+    :high_water_mark, :correction_open_since, :correction_windows, :high_water_mark_timeline,
+    keyword_init: true
+  )
+  private_constant :CorrectionState
+
+  # Returns { high_water_mark_timeline: [[date, high_water_mark], ...], correction_windows: [...] }
   def process_issue issue, column_map
     start_time = issue.started_stopped_times.first
-    return { hwm_timeline: [], correction_windows: [] } if start_time.nil?
-
-    high_water_mark = nil
-    correction_open_since = nil
-    correction_windows = []
-    hwm_timeline = [] # sorted chronologically by date
+    return { high_water_mark_timeline: [], correction_windows: [] } if start_time.nil?
 
+    state = CorrectionState.new(
+      high_water_mark: nil, correction_open_since: nil, correction_windows: [], high_water_mark_timeline: []
+    )
     issue.status_changes.each do |change|
       next if change.time < start_time
 
       col_index = column_map[change.value_id]
       next if col_index.nil?
 
-      if high_water_mark.nil? || col_index > high_water_mark
-        # Forward movement: advance hwm, close any open correction window, record timeline entry
-        if correction_open_since
-          correction_windows << {
-            start_date: correction_open_since,
-            end_date: change.time.to_date,
-            column_index: high_water_mark
-          }
-          correction_open_since = nil
-        end
-        high_water_mark = col_index
-        hwm_timeline << [change.time.to_date, high_water_mark]
-      elsif col_index == high_water_mark && correction_open_since
-        # Same-column recovery: close the correction window without changing hwm or adding timeline entry
-        correction_windows << {
-          start_date: correction_open_since,
-          end_date: change.time.to_date,
-          column_index: high_water_mark
-        }
-        correction_open_since = nil
-      elsif col_index < high_water_mark
-        # Backwards movement: open correction window if not already open
-        correction_open_since ||= change.time.to_date
-      end
+      apply_change(state, col_index, change.time.to_date)
     end
+    # A window still open at the end never recovered, so it runs to the end of the range.
+    close_correction(state, @date_range.end) if state.correction_open_since
+
+    { high_water_mark_timeline: state.high_water_mark_timeline, correction_windows: state.correction_windows }
+  end
 
-    if correction_open_since
-      correction_windows << {
-        start_date: correction_open_since,
-        end_date: @date_range.end,
-        column_index: high_water_mark
-      }
+  def apply_change state, col_index, date
+    if state.high_water_mark.nil? || col_index > state.high_water_mark
+      advance_high_water_mark(state, col_index, date)
+    elsif col_index == state.high_water_mark && state.correction_open_since
+      close_correction(state, date) # recovered back to the high water mark
+    elsif col_index < state.high_water_mark
+      state.correction_open_since ||= date # slipped behind; open a window if one isn't already open
     end
+  end
+
+  def advance_high_water_mark state, col_index, date
+    close_correction(state, date) if state.correction_open_since
+    state.high_water_mark = col_index
+    state.high_water_mark_timeline << [date, col_index]
+  end
 
-    { hwm_timeline: hwm_timeline, correction_windows: correction_windows }
+  def close_correction state, end_date
+    state.correction_windows << {
+      start_date: state.correction_open_since,
+      end_date: end_date,
+      column_index: state.high_water_mark
+    }
+    state.correction_open_since = nil
   end
 
-  def hwm_at hwm_timeline, date
+  def high_water_mark_at high_water_mark_timeline, date
     result = nil
-    hwm_timeline.each do |timeline_date, hwm|
+    high_water_mark_timeline.each do |timeline_date, high_water_mark|
       break if timeline_date > date
 
-      result = hwm
+      result = high_water_mark
     end
     result
   end
@@ -97,10 +99,10 @@ class CfdDataBuilder
     @date_range.each_with_object({}) do |date, result|
       counts = Array.new(column_count, 0)
       issue_states.each do |state|
-        hwm = hwm_at(state[:hwm_timeline], date)
-        next if hwm.nil?
+        high_water_mark = high_water_mark_at(state[:high_water_mark_timeline], date)
+        next if high_water_mark.nil?
 
-        (0..hwm).each { |i| counts[i] += 1 }
+        (0..high_water_mark).each { |i| counts[i] += 1 }
       end
       result[date] = counts
     end

data/lib/jirametrics/change_item.rb

@@ -14,17 +14,29 @@ class ChangeItem
     @field = @raw['field']
     @value = @raw['toString']
     @old_value = @raw['fromString']
-    if sprint?
-      @value_id = @raw['to'].split(', ').collect(&:to_i)
-      @old_value_id = (@raw['from'] || '').split(', ').collect(&:to_i)
-    else
-      @value_id = @raw['to']&.to_i
-      @old_value_id = @raw['from']&.to_i
-    end
+    @value_id, @old_value_id = parse_value_ids
     @field_id = @raw['fieldId']
     @artificial = artificial
   end
 
+  # Sprints carry a comma-separated list of ids in 'to'/'from', so those become arrays. Every other
+  # field is treated as a single id: to_i grabs the leading number, or 0 for text/bracketed values like
+  # Watchers or Markets (whose value_id is never used as a real id anyway).
+  def parse_value_ids
+    to = @raw['to']
+    from = @raw['from']
+    return [to&.to_i, from&.to_i] unless sprint?
+
+    [parse_multiple_integer_values(to), parse_multiple_integer_values(from)]
+  end
+
+  # Parses a comma-separated string of integers into a list. Sprint is the only field we currently parse
+  # this way, but the operation is generic - other fields may turn out to carry multiple ids too. to_s
+  # turns a nil (no value) into an empty list.
+  def parse_multiple_integer_values raw_value
+    raw_value.to_s.split(', ').collect(&:to_i)
+  end
+
   def author
     @author_raw&.[]('displayName') || @author_raw&.[]('name') || 'Unknown author'
   end