jirametrics 2.31 → 3.1

data/lib/jirametrics/daily_wip_by_blocked_stalled_chart.rb

@@ -40,20 +40,28 @@ class DailyWipByBlockedStalledChart < DailyWipChart
 
   def default_grouping_rules issue:, rules:
     started, stopped = issue.started_stopped_times
-    stopped_date = stopped&.to_date
     started_date = started&.to_date
+    stopped_date = stopped&.to_date
 
     date = rules.current_date
     change = issue.blocked_stalled_by_date(date_range: date..date, chart_end_time: time_range.end)[date]
-    stopped_today = stopped_date == rules.current_date
 
-    days = nil
-    if started_date && stopped_date
-      days = (stopped_date - started_date).to_i + 1 # cycletime
-    elsif started_date
-      days = (time_range.end.to_date - started_date).to_i + 1 # age
-    end
+    assign_group_rule(
+      rules, started: started, stopped_today: stopped_date == date, change: change,
+      days: days_between(started_date, stopped_date)
+    )
+  end
+
+  # The issue's cycle time when it has finished, its current age when it's still going, or nil when we
+  # don't even know when it started.
+  def days_between started_date, stopped_date
+    return (stopped_date - started_date).to_i + 1 if started_date && stopped_date
+    return (time_range.end.to_date - started_date).to_i + 1 if started_date
 
+    nil
+  end
+
+  def assign_group_rule rules, started:, stopped_today:, change:, days:
     if stopped_today && started.nil?
       @has_completed_but_not_started = true
       rules.label = 'Completed but not started'
@@ -69,7 +77,14 @@ class DailyWipByBlockedStalledChart < DailyWipChart
       rules.label = 'Start date unknown'
       rules.color = '--body-background'
       rules.group_priority = 4
-    elsif change&.blocked?
+    else
+      assign_in_progress_group_rule(rules, change: change, days: days)
+    end
+  end
+
+  # A started, not-yet-completed issue is grouped by its blocked/stalled state on the day.
+  def assign_in_progress_group_rule rules, change:, days:
+    if change&.blocked?
       rules.label = 'Blocked'
       rules.color = '--blocked-color'
       rules.group_priority = 1

data/lib/jirametrics/daily_wip_chart.rb

@@ -39,35 +39,47 @@ class DailyWipChart < ChartBase
     issue_rules_by_active_date = group_issues_by_active_dates
     possible_rules = select_possible_rules issue_rules_by_active_date
 
-    conflicting_labels = possible_rules
-      .group_by(&:label)
-      .select { |_label, rules| rules.any?(&:highlight) && rules.any? { |r| !r.highlight } }
-      .keys
+    data_sets = build_data_sets(possible_rules, issue_rules_by_active_date)
+    data_sets = prepend_trend_lines(data_sets) if @trend_lines
+
+    wrap_and_render(binding, __FILE__)
+  end
 
-    data_sets = possible_rules.collect do |grouping_rule|
-      suffix = conflicting_labels.include?(grouping_rule.label) && grouping_rule.highlight ? '*' : ''
+  def build_data_sets possible_rules, issue_rules_by_active_date
+    labels = conflicting_labels(possible_rules)
+    possible_rules.collect do |grouping_rule|
+      suffix = labels.include?(grouping_rule.label) && grouping_rule.highlight ? '*' : ''
       make_data_set grouping_rule: grouping_rule, issue_rules_by_active_date: issue_rules_by_active_date,
                     label_suffix: suffix
     end
-    if @trend_lines
-      data_sets = @trend_lines.filter_map do |group_labels, line_color|
-        trend_line_data_set(data: data_sets, group_labels: group_labels, color: line_color)
-      end + data_sets
-    end
+  end
 
-    wrap_and_render(binding, __FILE__)
+  # Labels that appear both highlighted and un-highlighted; the highlighted variant gets a '*' suffix so
+  # the two are distinguishable in the legend.
+  def conflicting_labels possible_rules
+    possible_rules
+      .group_by(&:label)
+      .select { |_label, rules| rules.any?(&:highlight) && rules.any? { |rule| !rule.highlight } }
+      .keys
+  end
+
+  def prepend_trend_lines data_sets
+    @trend_lines.filter_map do |group_labels, line_color|
+      trend_line_data_set(data: data_sets, group_labels: group_labels, color: line_color)
+    end + data_sets
   end
 
   def default_header_text = 'Daily WIP'
   def default_description_text = ''
 
-  def default_grouping_rules issue:, rules: # rubocop:disable Lint/UnusedMethodArgument
+  def default_grouping_rules issue:, rules:
     raise 'If you use this class directly then you must provide grouping_rules'
   end
 
   def select_possible_rules issue_rules_by_active_date
     possible_rules = []
     issue_rules_by_active_date.each_pair do |_date, issues_rules_list|
+      # issues_rules_list is an array of [issue, rule] pairs, not a hash, so this isn't each_value.
       issues_rules_list.each do |_issue, rules| # rubocop:disable Style/HashEachMethods
         possible_rules << rules unless possible_rules.any? { |r| r.group == rules.group }
       end
@@ -77,17 +89,8 @@ class DailyWipChart < ChartBase
 
   def group_issues_by_active_dates
     hash = {}
-
     @issues.each do |issue|
-      start, stop = cycletime_for_issue(issue).started_stopped_dates(issue)
-      next if start.nil? && stop.nil?
-
-      # If it stopped but never started then assume it started at creation so the data points
-      # will be available for the config.
-      start = issue.created.to_date if stop && start.nil?
-      start = @date_range.begin if start < @date_range.begin
-
-      start.upto(stop || @date_range.end) do |date|
+      active_dates_for(issue)&.each do |date|
         rule = configure_rule issue: issue, date: date
         (hash[date] ||= []) << [issue, rule] unless rule.ignored?
       end
@@ -95,44 +98,64 @@ class DailyWipChart < ChartBase
     hash
   end
 
+  # The range of dates an issue is "active" on the chart: from when it started - or its creation, if it
+  # stopped without a recorded start - through when it stopped, or the end of the range if still open.
+  # Returns nil when the issue neither started nor stopped.
+  def active_dates_for issue
+    start, stop = cycletime_for_issue(issue).started_stopped_dates(issue)
+    return nil if start.nil? && stop.nil?
+
+    # Past the guard, a nil start means it only stopped, so treat creation as the start.
+    start = issue.created.to_date if start.nil?
+    start = @date_range.begin if start < @date_range.begin
+    start..(stop || @date_range.end)
+  end
+
   def make_data_set grouping_rule:, issue_rules_by_active_date:, label_suffix: ''
     positive = grouping_rule.group_priority >= 0
     display_label = "#{grouping_rule.label}#{label_suffix}"
 
     data = issue_rules_by_active_date.collect do |date, issue_rules|
-      issue_strings = issue_rules
-        .select { |_issue, rules| rules.group == grouping_rule.group }
-        .sort_by { |issue, _rules| issue.key_as_i }
-        .collect { |issue, rules| "#{issue.key} : #{issue.summary.strip} #{rules.issue_hint}" }
-      title_label = grouping_rule.label_hint || display_label
-      title = ["#{title_label} (#{label_issues issue_strings.size})"] + issue_strings
-
-      {
-        x: date,
-        y: positive ? issue_strings.size : -issue_strings.size,
-        title: title
-      }
+      datapoint_for date: date, issue_rules: issue_rules, grouping_rule: grouping_rule,
+                    display_label: display_label, positive: positive
     end
 
-    color = grouping_rule.color || random_color
-    background_color = if grouping_rule.highlight
-                         RawJavascript.new("createDiagonalPattern(#{color.to_json})")
-                       else
-                         color
-                       end
-
     {
       type: 'bar',
       label: display_label,
       label_hint: grouping_rule.label_hint,
       data: data,
-      backgroundColor: background_color,
+      backgroundColor: background_color_for(grouping_rule),
       borderColor: CssVariable['--wip-chart-border-color'],
       borderWidth: grouping_rule.color.to_s == 'var(--body-background)' ? 1 : 0,
       borderRadius: positive ? 0 : 5
     }
   end
 
+  # One {x, y, title} point: the issues active on this date that belong to this rule's group, with a
+  # title listing them. y is negated for negative-priority groups so they render below the axis.
+  def datapoint_for date:, issue_rules:, grouping_rule:, display_label:, positive:
+    issue_strings = issue_strings_for issue_rules, grouping_rule
+    title_label = grouping_rule.label_hint || display_label
+    title = ["#{title_label} (#{label_issues issue_strings.size})"] + issue_strings
+
+    { x: date, y: positive ? issue_strings.size : -issue_strings.size, title: title }
+  end
+
+  def issue_strings_for issue_rules, grouping_rule
+    issue_rules
+      .select { |_issue, rules| rules.group == grouping_rule.group }
+      .sort_by { |issue, _rules| issue.key_as_i }
+      .collect { |issue, rules| "#{issue.key} : #{issue.summary.strip} #{rules.issue_hint}" }
+  end
+
+  def background_color_for grouping_rule
+    color = grouping_rule.color || random_color
+    return color unless grouping_rule.highlight
+
+    RawJavascript.new("createDiagonalPattern(#{color.to_json})")
+  end
+
   def configure_rule issue:, date:
     raise "#{self.class}: grouping_rules must be set" if @group_by_block.nil?
 
@@ -150,7 +173,8 @@ class DailyWipChart < ChartBase
     (@trend_lines ||= []) << [group_labels, line_color]
   end
 
-  def trend_line_data_set data:, group_labels:, color:
+  # Sums the daily WIP across every dataset whose label is in group_labels, giving { date => total_wip }.
+  def daily_wip_totals data, group_labels
     day_wip_hash = {}
     data.each do |top_level|
       next unless group_labels.include? top_level[:label]
@@ -160,8 +184,11 @@ class DailyWipChart < ChartBase
         day_wip_hash[date] = (day_wip_hash[date] || 0) + datapoint[:y]
       end
     end
+    day_wip_hash
+  end
 
-    points = day_wip_hash
+  def trend_line_data_set data:, group_labels:, color:
+    points = daily_wip_totals(data, group_labels)
       .collect { |date, wip| [date.jd, wip] }
       .sort_by(&:first)
 

data/lib/jirametrics/data_quality_report.rb

@@ -28,9 +28,15 @@ class DataQualityReport < ChartBase
     description_text <<-HTML
       <p>
         We have a tendency to assume that anything we see in a chart is 100% accurate, although that's
-        not always true. To understand the accuracy of the chart, we have to understand how accurate the
-        initial data was and also how much of the original data set was used in the chart. This section
-        will hopefully give you enough information to make that decision.
+        not always true. The accuracy of a chart depends both on how good the underlying data was and
+        on how much of that data actually made it into the chart.
+      </p>
+      <p>
+        The items highlighted below are not necessarily bad data. Some are genuine contradictions worth
+        fixing in Jira, such as an item finishing before it started. But many are simply places where the
+        way your team actually works bumps up against the simplified start-to-finish model this tool uses
+        to compute flow metrics. Those aren't mistakes; we flag them so you can read the charts with the
+        right context, not because anyone did anything wrong.
       </p>
     HTML
   end
@@ -128,15 +134,7 @@ class DataQualityReport < ChartBase
       Entry.new started: started, stopped: stopped, issue: issue
     end
 
-    @entries.sort! do |a, b|
-      a.issue.key =~ /.+-(\d+)$/
-      a_id = $1.to_i
-
-      b.issue.key =~ /.+-(\d+)$/
-      b_id = $1.to_i
-
-      a_id <=> b_id
-    end
+    @entries.sort_by! { |entry| entry.issue.key_as_i }
   end
 
   def scan_for_completed_issues_without_a_start_time entry:
@@ -174,56 +172,66 @@ class DataQualityReport < ChartBase
   end
 
   def scan_for_backwards_movement entry:, backlog_statuses:
-    issue = entry.issue
-
     # Moving backwards through statuses is bad. Moving backwards through status categories is almost always worse.
     last_index = -1
-    issue.changes.each do |change|
+    entry.issue.changes.each do |change|
       next unless change.status?
 
       board = entry.issue.board
-      index = entry.issue.board.visible_columns.find_index { |column| column.status_ids.include? change.value_id }
+      index = column_index_for(board, change)
       if index.nil?
-        # If it's a backlog status then ignore it. Not supposed to be visible.
-        next if entry.issue.board.backlog_statuses.include?(board.possible_statuses.find_by_id(change.value_id))
-
-        detail = "Status #{format_status change, board: board} is not on the board"
-        if issue.board.possible_statuses.find_by_id(change.value_id).nil?
-          detail = "Status #{format_status change, board: board} cannot be found at all. Was it deleted?"
-        end
-
-        # If it's been moved back to backlog then it's on a different report. Ignore it here.
-        detail = nil if backlog_statuses.any? { |s| s.name == change.value }
-
-        entry.report(problem_key: :issue_not_visible_on_board, detail: detail) unless detail.nil?
+        report_status_not_on_board(entry: entry, change: change, board: board, backlog_statuses: backlog_statuses)
       elsif change.old_value.nil?
-        # Do nothing
+        # A move onto the board with no prior status has nothing to compare against.
       elsif index < last_index
-        new_category = board.possible_statuses.find_by_id(change.value_id).category.name
-        old_category = board.possible_statuses.find_by_id(change.old_value_id).category.name
-
-        if new_category == old_category
-          entry.report(
-            problem_key: :backwords_through_statuses,
-            detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
-              " to #{format_status change, board: board}" \
-              " on #{change.time.to_date}"
-          )
-        else
-          entry.report(
-            problem_key: :backwards_through_status_categories,
-            detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
-              " to #{format_status change, board: board}" \
-              " on #{change.time.to_date}," \
-              " crossing from category #{format_status change, use_old_status: true, board: board, is_category: true}" \
-              " to #{format_status change, board: board, is_category: true}."
-          )
-        end
+        report_backwards_movement(entry: entry, change: change, board: board)
       end
       last_index = index || -1
     end
   end
 
+  def column_index_for board, change
+    board.visible_columns.find_index { |column| column.status_ids.include? change.value_id }
+  end
+
+  def report_status_not_on_board entry:, change:, board:, backlog_statuses:
+    # If it's a backlog status then ignore it. Not supposed to be visible.
+    return if board.backlog_statuses.include?(board.possible_statuses.find_by_id(change.value_id))
+
+    detail = "Status #{format_status change, board: board} is not on the board"
+    if board.possible_statuses.find_by_id(change.value_id).nil?
+      detail = "Status #{format_status change, board: board} cannot be found at all. Was it deleted?"
+    end
+
+    # If it's been moved back to backlog then it's on a different report. Ignore it here.
+    detail = nil if backlog_statuses.any? { |s| s.name == change.value }
+
+    entry.report(problem_key: :issue_not_visible_on_board, detail: detail) unless detail.nil?
+  end
+
+  def report_backwards_movement entry:, change:, board:
+    new_category = board.possible_statuses.find_by_id(change.value_id).category.name
+    old_category = board.possible_statuses.find_by_id(change.old_value_id).category.name
+
+    if new_category == old_category
+      entry.report(
+        problem_key: :backwords_through_statuses,
+        detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
+          " to #{format_status change, board: board}" \
+          " on #{change.time.to_date}"
+      )
+    else
+      entry.report(
+        problem_key: :backwards_through_status_categories,
+        detail: "Moved from #{format_status change, use_old_status: true, board: board}" \
+          " to #{format_status change, board: board}" \
+          " on #{change.time.to_date}," \
+          " crossing from category #{format_status change, use_old_status: true, board: board, is_category: true}" \
+          " to #{format_status change, board: board, is_category: true}."
+      )
+    end
+  end
+
   def scan_for_issue_not_in_active_sprint entry:
     issue = entry.issue
     return unless issue.board.scrum?
@@ -248,7 +256,7 @@ class DataQualityReport < ChartBase
   end
 
   def scan_for_issues_not_created_in_a_backlog_status entry:, backlog_statuses:
-    creation_change = entry.issue.changes.find { |issue| issue.status? }
+    creation_change = entry.issue.changes.find(&:status?)
 
     return if backlog_statuses.any? { |status| status.id == creation_change.value_id }
 
@@ -325,18 +333,7 @@ class DataQualityReport < ChartBase
   def scan_for_incomplete_subtasks_when_issue_done entry:
     return unless entry.stopped
 
-    subtask_labels = entry.issue.subtasks.filter_map do |subtask|
-      subtask_started, subtask_stopped = subtask.started_stopped_times
-
-      if !subtask_started && !subtask_stopped
-        "#{subtask_label subtask} (Not even started)"
-      elsif !subtask_stopped
-        "#{subtask_label subtask} (Still not done)"
-      elsif subtask_stopped > entry.stopped
-        "#{subtask_label subtask} (Closed #{time_as_english entry.stopped, subtask_stopped} later)"
-      end
-    end
-
+    subtask_labels = entry.issue.subtasks.filter_map { |subtask| incomplete_subtask_label subtask, entry.stopped }
     return if subtask_labels.empty?
 
     entry.report(
@@ -345,10 +342,17 @@ class DataQualityReport < ChartBase
     )
   end
 
-  def label_issues number
-    return '1 item' if number == 1
+  # The label for one subtask that isn't finished when its parent is done, or nil if it is fine.
+  def incomplete_subtask_label subtask, issue_stopped
+    subtask_started, subtask_stopped = subtask.started_stopped_times
 
-    "#{number} items"
+    if !subtask_started && !subtask_stopped
+      "#{subtask_label subtask} (Not even started)"
+    elsif !subtask_stopped
+      "#{subtask_label subtask} (Still not done)"
+    elsif subtask_stopped > issue_stopped
+      "#{subtask_label subtask} (Closed #{time_as_english issue_stopped, subtask_stopped} later)"
+    end
   end
 
   def scan_for_discarded_data entry:
@@ -470,7 +474,7 @@ class DataQualityReport < ChartBase
 
   def render_incomplete_subtasks_when_issue_done problems
     <<-HTML
-      #{label_issues problems.size} issues were marked as done while subtasks were still not done.
+      #{label_issues problems.size} were marked as done while subtasks were still not done.
     HTML
   end
 

data/lib/jirametrics/dependency_chart.rb

@@ -14,6 +14,7 @@ class DependencyChart < ChartBase
       @merge_bidirectional = keep.to_sym
     end
 
+    # get_ prefix because the plain name is the config DSL setter (merge_bidirectional keep:).
     def get_merge_bidirectional # rubocop:disable Naming/AccessorMethodName
       @merge_bidirectional
     end
@@ -135,34 +136,46 @@ class DependencyChart < ChartBase
       @link_rules_block.call link, link_rules
 
       next if link_rules.ignored?
-
-      if link_rules.get_merge_bidirectional
-        opposite = issue_links.find do |l|
-          l.name == link.name && l.origin.key == link.other_issue.key && l.other_issue.key == link.origin.key
-        end
-        if opposite
-          # rubocop:disable Style/GuardClause
-          if link_rules.get_merge_bidirectional.to_sym == link.direction
-            # We keep this one and discard the opposite
-            links_to_ignore << opposite
-          else
-            # We keep the opposite and discard this one
-            next
-          end
-          # rubocop:enable Style/GuardClause
-        end
-      end
+      next if merge_bidirectional_skip?(link, link_rules, issue_links, links_to_ignore)
 
       link_graph << make_dot_link(issue_link: link, link_rules: link_rules)
-
       visible_issues[link.origin.key] = link.origin
       visible_issues[link.other_issue.key] = link.other_issue
     end
 
-    dot_graph = []
-    dot_graph << 'digraph mygraph {'
-    dot_graph << 'rankdir=LR'
-    dot_graph << 'bgcolor="transparent"'
+    return nil if visible_issues.empty?
+
+    assemble_dot_graph(visible_issues, link_graph)
+  end
+
+  # For a bidirectional-merge link, collapses the pair into one. When this link is the one to keep, its
+  # opposite is added to links_to_ignore; returns true when this link should be skipped in favour of its
+  # opposite. Returns false (keep this link) when there's no merge or no matching opposite.
+  def merge_bidirectional_skip? link, link_rules, issue_links, links_to_ignore
+    merge_direction = link_rules.get_merge_bidirectional
+    return false unless merge_direction
+
+    opposite = find_opposite_link(link, issue_links)
+    return false unless opposite
+
+    if merge_direction.to_sym == link.direction
+      links_to_ignore << opposite # keep this one, discard the opposite
+      false
+    else
+      true # keep the opposite, skip this one
+    end
+  end
+
+  def find_opposite_link link, issue_links
+    issue_links.find do |candidate|
+      candidate.name == link.name &&
+        candidate.origin.key == link.other_issue.key &&
+        candidate.other_issue.key == link.origin.key
+    end
+  end
+
+  def assemble_dot_graph visible_issues, link_graph
+    dot_graph = ['digraph mygraph {', 'rankdir=LR', 'bgcolor="transparent"']
 
     # Sort the keys so they are proccessed in a deterministic order.
     visible_issues.values.sort_by(&:key_as_i).each do |issue|
@@ -171,12 +184,7 @@ class DependencyChart < ChartBase
       dot_graph << make_dot_issue(issue: issue, issue_rules: rules)
     end
 
-    dot_graph += link_graph
-    dot_graph << '}'
-
-    return nil if visible_issues.empty?
-
-    dot_graph
+    dot_graph + link_graph + ['}']
   end
 
   def execute_graphviz dot_graph
@@ -193,9 +201,10 @@ class DependencyChart < ChartBase
 
   def shrink_svg svg
     scale = 0.8
-    svg.sub(/width="([\d.]+)pt" height="([\d.]+)pt"/) do
-      width = $1.to_i * scale
-      height = $2.to_i * scale
+    svg.sub(/width="(?<width_pt>[\d.]+)pt" height="(?<height_pt>[\d.]+)pt"/) do
+      match = Regexp.last_match
+      width = match[:width_pt].to_i * scale
+      height = match[:height_pt].to_i * scale
       "width=\"#{width.to_i}pt\" height=\"#{height.to_i}pt\""
     end
   end

data/lib/jirametrics/download_config.rb

@@ -39,7 +39,4 @@ class DownloadConfig
     date = @no_earlier_than if date.nil? && @no_earlier_than
     date
   end
-
-  private
-
 end

data/lib/jirametrics/downloader.rb

@@ -244,18 +244,19 @@ class Downloader
     # Only use the saved metadata if the version number is the same one that we're currently using.
     # If the cached data is in an older format then we're going to throw most of it away.
     @cached_data_format_is_current = (hash['version'] || 0) == CURRENT_METADATA_VERSION
-    if @cached_data_format_is_current
-      hash.each do |key, value|
-        value = Date.parse(value) if value.is_a?(String) && value =~ /^\d{4}-\d{2}-\d{2}$/
-        @metadata[key] = value
-      end
-
-    end
+    load_cached_metadata(hash) if @cached_data_format_is_current
 
     # Even if this is the old format, we want to obey this one tag
     @metadata['no-download'] = hash['no-download'] if hash['no-download']
   end
 
+  def load_cached_metadata hash
+    hash.each do |key, value|
+      value = Date.parse(value) if value.is_a?(String) && value =~ /^\d{4}-\d{2}-\d{2}$/
+      @metadata[key] = value
+    end
+  end
+
   def timezone_offset
     @download_config.project_config.exporter.timezone_offset
   end
@@ -339,21 +340,45 @@ class Downloader
       return
     end
 
-    prs = @download_config.github_repos.flat_map do |repo|
-      GithubGateway.new(
-        repo: repo,
-        project_keys: project_keys,
-        file_system: @file_system,
-        raw_pr_cache: @github_pr_cache
-      ).fetch_pull_requests(since: @download_date_range&.begin)
+    prs = []
+    any_repo_failed = false
+    @download_config.github_repos.each do |repo|
+      prs.concat(
+        GithubGateway.new(
+          repo: repo,
+          project_keys: project_keys,
+          file_system: @file_system,
+          raw_pr_cache: @github_pr_cache
+        ).fetch_pull_requests(since: @download_date_range&.begin)
+      )
+    rescue StandardError => e
+      any_repo_failed = true
+      warn_about_failed_pr_download(repo, e)
     end
 
+    # A successful-but-empty fetch is a legitimate result and gets saved. But if any repo raised, we
+    # can't produce a complete file, so we leave the previously downloaded data untouched.
+    return if any_repo_failed
+
     @file_system.save_json(
       json: prs.map(&:raw),
       filename: File.join(@target_path, "#{file_prefix}_github_prs.json")
     )
   end
 
+  # The same github_repos are downloaded for every project, so an unreachable repo would otherwise
+  # warn once per project (dozens of identical messages). The github_pr_cache is shared across all
+  # projects in a run, so we use it to warn about each repo at most once.
+  def warn_about_failed_pr_download repo, error
+    warned_key = [repo, :download_failure_warned]
+    return if @github_pr_cache[warned_key]
+
+    @github_pr_cache[warned_key] = true
+    @file_system.warning "Failed to download pull requests from #{repo}: #{error.message}. " \
+      'Left the existing PR data in place rather than overwriting it with an incomplete set. ' \
+      'Fix the access problem (often a `gh auth login` / repo-access issue) and re-run download to refresh it.'
+  end
+
   def extract_project_keys_from_downloaded_issues
     path = File.join(@target_path, "#{file_prefix}_issues")
     return [] unless @file_system.dir_exist?(path)