jirametrics 3.0 → 3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8411199c48209ed18008a509523bcd28c7d22c1145b492137ac5219972f35245
-  data.tar.gz: 3074f95dfc4b401408e615d71b957f5e5626514a6172de5855ec80a15a9bc82a
+  metadata.gz: 39b2d5045ef29e8ea0b33e8b9134ba66a564a6c92f0c607f4bcc706512659393
+  data.tar.gz: 1b40c073695046589fe0d8ca996d0337eb81fda0ffb44ac7875f238369a88d11
 SHA512:
-  metadata.gz: 1b7dc5f5abea1401da94464b80cb8b346f503055d5df92bac596af7c48b3021d4deb641af804710186a964f4d750b6d03a542cb9236c852b12e174887ba2def9
-  data.tar.gz: d9b6de864972518ae2a3ab91c92fc4eba3d411232b252afb31c041ea9575cfa1cebee4085211d0d1eb091335240da5a13038622765dc0ef3fd8c73f874ee4222
+  metadata.gz: e614e62715f71e657557718fbebf5174199b46b30b3f9fa93de230862830d4a902336ef28262e30fe77082e244222ca823f4c41314d4ac424a98c8524540a0da
+  data.tar.gz: bba299cd94305c9bd0cac2f271235eca287b44b33a77e7e86597aecb662373e71b82b91a074b1ba1e773a4011620a7335cf33b1540810ffe283b89be6554b18f

data/lib/jirametrics/atlassian_document_format.rb

@@ -39,7 +39,7 @@ class AtlassianDocumentFormat
   # https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
   #
   # 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
+  # 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|

data/lib/jirametrics/chart_base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class ChartBase
-  # Okabe-Ito palette — perceptually distinct under the most common forms of colour blindness.
+  # Okabe-Ito palette - perceptually distinct under the most common forms of colour blindness.
   # Ordered from most- to least-commonly useful for chart series.
   OKABE_ITO_PALETTE = %w[
     #0072B2

data/lib/jirametrics/cumulative_flow_diagram.rb

@@ -46,7 +46,7 @@ class CumulativeFlowDiagram < ChartBase
         total work entered; the top edge of the rightmost band shows total work completed.
       </div>
       <div class="p">
-        A widening band means work is piling up in that stage — a bottleneck. Parallel top edges
+        A widening band means work is piling up in that stage - a bottleneck. Parallel top edges
         (bands staying the same width) indicate smooth flow. Steep rises in the leftmost band
         without corresponding rises on the right mean new work is arriving faster than it is
         being finished.

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

data/lib/jirametrics/downloader.rb

@@ -340,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)

data/lib/jirametrics/downloader_for_cloud.rb

@@ -168,7 +168,7 @@ class DownloaderForCloud < Downloader
       log "        #{key} worklogs: page startAt=#{start_at}, " \
           "received=#{worklogs.size}, fetched=#{all_worklogs.size}/#{total}"
       break if all_worklogs.size >= total
-      # Guard against Jira reporting a higher total than it will actually return — seen when
+      # Guard against Jira reporting a higher total than it will actually return - seen when
       # worklogs are deleted or access-restricted after the initial fetch. Without this,
       # start_at never advances and we loop forever requesting the same empty page.
       break if worklogs.empty?
@@ -344,7 +344,7 @@ class DownloaderForCloud < Downloader
     end
   end
 
-  # Scan up-to-date cached primary issues we haven't checked yet — they may reference related
+  # Scan up-to-date cached primary issues we haven't checked yet - they may reference related
   # issues that are not in the primary query result. We only follow links one hop out from the
   # primary issues, so related (non-primary) cached issues are not followed (just logged).
   def scan_cached_issues_for_related issue_data_hash:, board:, checked_for_related:, related_issue_keys:
@@ -400,7 +400,7 @@ class DownloaderForCloud < Downloader
 
   # We only follow links one hop out from the primary (board) issues. If a related issue
   # itself references further issues we haven't already downloaded, we deliberately don't
-  # follow them — but log it so we can diagnose later if an export fails because a
+  # follow them - but log it so we can diagnose later if an export fails because a
   # second-hop issue was missing. See GitHub #72.
   def log_unfollowed_related_keys issue:, issue_data_hash:
     onward = related_keys_for(issue).reject { |key| issue_data_hash[key] }

data/lib/jirametrics/exporter.rb

@@ -6,13 +6,22 @@ class Exporter
   attr_reader :project_configs
   attr_accessor :file_system
 
+  def self.logfile_name
+    @logfile_name ||= 'jirametrics.log'
+  end
+
+  # The MCP server sets this to a separate file so starting the server doesn't clobber the
+  # export/debug log (jirametrics.log) that someone may be mid-debug on.
+  class << self
+    attr_writer :logfile_name
+  end
+
   def self.configure &block
-    logfile_name = 'jirametrics.log'
     # No block form: FileSystem holds this descriptor open for the whole run and writes to it as we
     # go, so it must outlive this method.
     logfile = File.open(logfile_name, 'w') # rubocop:disable Style/FileOpen
   rescue Errno::EACCES
-    # FileSystem can't be used here — it hasn't been created yet (it depends on this logfile).
+    # FileSystem can't be used here - it hasn't been created yet (it depends on this logfile).
     warn "Error: Cannot write to #{File.expand_path(logfile_name)}. " \
       'Please ensure the current directory is writable.'
     exit 1
@@ -73,6 +82,179 @@ class Exporter
     puts "Full output from downloader in #{file_system.logfile_name}"
   end
 
+  def verify_jira_connections name_filter:
+    results = []
+    begin
+      # Probe under log_only so the gateway's raw curl chatter (and its error dumps) stay in the
+      # logfile rather than cluttering the console; we surface a clean summary line below.
+      file_system.log_only = true
+      jira_connections_to_verify(name_filter: name_filter).each do |config, settings|
+        gateway = JiraGateway.new(file_system: file_system, jira_config: config, settings: settings)
+        results << gateway.verify_connection
+      end
+    ensure
+      file_system.log_only = false
+    end
+
+    if results.empty?
+      file_system.error 'No Jira connection found in the configuration to verify'
+      return results
+    end
+    results.each { |result| file_system.log result.message, also_write_to_stderr: true }
+    results
+  end
+
+  # The [jira_config, settings] pairs to verify, deduplicated by URL. We do NOT evaluate_next_level:
+  # running a project block (e.g. standard_project) forces an issue-data load that doesn't exist
+  # before the first download, and verify must work pre-download. When no project supplied a
+  # connection we fall back to the top-level jira_config, so verify can run as a first setup step on
+  # just the credentials file. (The fallback has no per-project settings, so a config-block-only
+  # setting like ignore_ssl_errors isn't applied. That only affects self-signed
+  # Data Center instances.)
+  def jira_connections_to_verify name_filter:
+    connections = []
+    seen_urls = []
+    each_project_config(name_filter: name_filter) do |project|
+      url = project.jira_config && project.jira_config['url']
+      next if url.nil? || seen_urls.include?(url)
+
+      seen_urls << url
+      connections << [project.jira_config, project.settings]
+    end
+    connections << [jira_config, {}] if connections.empty? && jira_config
+    connections
+  end
+
+  def boards board_id:, name_filter: nil
+    gateway = JiraGateway.new(file_system: file_system, jira_config: jira_config, settings: {})
+    # Keep the gateway's raw curl chatter in the logfile; list_boards/describe_board switch this off
+    # right before they print their own clean output, and the rescue turns a failed Jira call into a
+    # one-line message with next steps instead of a stack trace.
+    file_system.log_only = true
+    if board_id.nil?
+      list_boards gateway, name_filter
+    else
+      describe_board gateway, board_id
+    end
+    true
+  rescue StandardError
+    file_system.log_only = false
+    file_system.error boards_error_message(board_id)
+    false
+  ensure
+    file_system.log_only = false
+  end
+
+  def boards_error_message board_id
+    if board_id
+      "Couldn't read board #{board_id} from Jira. Check the id (run `jirametrics boards` to list them) " \
+        "and your credentials (`jirametrics verify`). Details in #{file_system.logfile_name}."
+    else
+      "Couldn't list boards from Jira. Check your credentials with `jirametrics verify`. " \
+        "Details in #{file_system.logfile_name}."
+    end
+  end
+
+  def list_boards gateway, name_filter
+    boards = fetch_all_boards gateway
+    boards.select! { |board| File.fnmatch(name_filter, board['name'].to_s, File::FNM_CASEFOLD) } if name_filter
+    boards.sort_by! { |board| board['name'].to_s.strip.downcase }
+    file_system.log_only = false # gateway calls done; turn logging back on to print results
+
+    if boards.empty?
+      file_system.log(
+        name_filter ? "No boards match #{name_filter.inspect}." : 'No boards found for this Jira connection.',
+        also_write_to_stderr: true
+      )
+      return
+    end
+
+    lines = ['Boards you can access:', '']
+    boards.each { |board| lines << "  #{board['id']}: #{board['name'].inspect} (#{board['type']})" }
+    lines << ''
+    lines << "Run `jirametrics boards <id>` to see a board's columns and choose cycletime points."
+    file_system.log lines.join("\n"), also_write_to_stderr: true
+  end
+
+  def fetch_all_boards gateway
+    boards = []
+    start_at = 0
+    loop do
+      json = gateway.call_url relative_url: "/rest/agile/1.0/board?startAt=#{start_at}&maxResults=50"
+      values = json['values'] || []
+      boards.concat values
+      break if json['isLast'] || values.empty?
+
+      start_at += values.length
+    end
+    boards
+  end
+
+  def describe_board gateway, board_id
+    statuses = StatusCollection.new
+    gateway.call_url(relative_url: '/rest/api/2/status').each do |snippet|
+      statuses << Status.from_raw(snippet)
+    end
+    raw = gateway.call_url relative_url: "/rest/agile/1.0/board/#{board_id}/configuration"
+    features = board_features(gateway, board_id, raw)
+    file_system.log_only = false # gateway calls done; turn logging back on to print results
+    board = Board.new raw: raw, possible_statuses: statuses, features: features
+    file_system.log format_board(board, board_id), also_write_to_stderr: true
+  end
+
+  # Only a team-managed ("simple") board needs the features lookup to tell sprints from kanban; for
+  # classic scrum/kanban the board type alone settles it, so we skip the extra request.
+  def board_features gateway, board_id, raw
+    return [] unless raw['type'] == 'simple'
+
+    BoardFeature.from_raw gateway.call_url(relative_url: "/rest/agile/1.0/board/#{board_id}/features")
+  end
+
+  def format_board board, board_id
+    lines = ["Board #{board_id}: #{board.name.inspect} (#{board_kind_label board})", '']
+
+    backlog = board.backlog_statuses
+    unless backlog.empty?
+      lines << 'Not shown on the board (treated as not started):'
+      backlog.each { |status| lines << "  - #{format_status status}" }
+      lines << ''
+    end
+
+    lines << 'Columns, left to right, with the statuses in each (shown as "name":id with its category):'
+    lines << ''
+    board.visible_columns.each do |column|
+      lines << "  #{column.name}"
+      column.status_ids.each do |id|
+        status = board.possible_statuses.find_by_id id
+        lines << "    - #{status ? format_status(status) : "unknown status id #{id}"}"
+      end
+    end
+
+    lines << ''
+    lines << 'To set cycle time, choose the column where work is "started" and where it is "finished":'
+    lines << "  start_at first_time_in_or_right_of_column '<started column>'"
+    lines << "  stop_at  first_time_in_or_right_of_column '<finished column>'"
+    if board.scrum?
+      lines << ''
+      lines << 'This board uses sprints. If no column cleanly marks when work starts, you can start the'
+      lines << 'clock when an item is first added to a sprint instead:'
+      lines << '  start_at first_time_added_to_active_sprint'
+    end
+    lines.join "\n"
+  end
+
+  # A team-managed ("simple") board can be scrum- or kanban-flavoured depending on its sprints
+  # feature; the bare "simple" from Jira doesn't say which, so spell it out.
+  def board_kind_label board
+    return board.board_type unless board.board_type == 'simple'
+
+    board.scrum? ? 'team-managed, uses sprints' : 'team-managed, no sprints'
+  end
+
+  def format_status status
+    "#{status.name.inspect}:#{status.id} (#{status.category.name})"
+  end
+
   def info key, name_filter:
     selected = []
     file_system.log_only = true

data/lib/jirametrics/github_gateway.rb

@@ -28,12 +28,27 @@ class GithubGateway
 
   def fetch_pull_requests since: nil
     raw_prs = @raw_pr_cache[[@repo, since]] ||= fetch_raw_pull_requests(since: since)
+    verify_repo_reachable_when_empty(raw_prs, since: since)
     prefetch_commit_messages(raw_prs)
     raw_prs.filter_map { |pr| build_pr_data(pr) }
   end
 
+  # `gh pr list --search` (the path taken whenever a `since` date is set) goes through GitHub's
+  # search API, which returns an empty result with a SUCCESS status for a repo we can't actually
+  # access, rather than erroring the way a direct repo query does. Downstream that empty would
+  # overwrite previously downloaded PR data. So when a search comes back empty, confirm the repo is
+  # genuinely reachable; if it isn't, raise so the caller treats it as a failed download and keeps
+  # the existing data instead of replacing it with nothing.
+  def verify_repo_reachable_when_empty raw_prs, since:
+    return unless since && raw_prs.empty?
+    return if repo_reachable?
+
+    raise "GitHub returned no pull requests for #{@repo} and the repository is not reachable " \
+      '(check your access to it and the URL in github_repos)'
+  end
+
   def fetch_raw_pull_requests since: nil
-    # NOTE: 'commits' is intentionally excluded — including it triggers GitHub's GraphQL node
+    # NOTE: 'commits' is intentionally excluded - including it triggers GitHub's GraphQL node
     # limit (authors sub-connection × PRs × commits exceeds 500,000 nodes). Branch name,
     # title, and body are sufficient for issue key extraction in the vast majority of cases.
     json_fields = %w[number title body headRefName createdAt closedAt mergedAt
@@ -177,12 +192,31 @@ class GithubGateway
     Regexp.new("\\b(?:#{keys_pattern})-\\d+(?![A-Za-z0-9])")
   end
 
+  # Cached per repo (reachability doesn't depend on the `since` window) so we probe at most once even
+  # when several projects share the same repo. Uses key? rather than ||= because a false verdict must
+  # stick and not trigger a re-probe on every project.
+  def repo_reachable?
+    key = [@repo, :reachable]
+    return @raw_pr_cache[key] if @raw_pr_cache.key?(key)
+
+    @raw_pr_cache[key] = probe_repo_reachable
+  end
+
+  def probe_repo_reachable
+    # This is expected to fail for an inaccessible repo, and the caller turns that into a single
+    # actionable warning, so suppress run_command's own failure warning to avoid stacking messages.
+    run_command(['repo', 'view', @repo, '--json', 'name'], warn_on_failure: false)
+    true
+  rescue StandardError
+    false
+  end
+
   def monotonic_time
     # In its own method so we can mock it out in tests
     Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
-  def run_command args
+  def run_command args, warn_on_failure: true
     attempts = 0
     loop do
       attempts += 1
@@ -199,7 +233,7 @@ class GithubGateway
       unless status.success?
         error_message = "  GitHub CLI command failed for #{@repo} " \
                         "(attempt #{attempts}/#{MAX_RETRIES}): #{stderr.strip}"
-        # stderr is a String (from Open3.capture3), so this include? is String#include? — a substring
+        # stderr is a String (from Open3.capture3), so this include? is String#include? - a substring
         # match ("does the error text contain this phrase?"), not Array membership. Style/ArrayIntersect
         # can't tell the two apart; its `.intersect?(stderr)` rewrite would be an exact-equality check
         # that never matches, silently killing the retry-on-transient-error logic.
@@ -212,19 +246,11 @@ class GithubGateway
           next
         end
         # rubocop:enable Style/ArrayIntersect
-        @file_system.warning error_message
+        @file_system.warning error_message if warn_on_failure
         raise "GitHub CLI command failed for #{@repo}: #{stderr}"
       end
 
-      return parse_command_result(stdout)
-    end
-  end
-
-  def parse_command_result stdout
-    result = JSON.parse(stdout)
-    if result.nil? || (result.is_a?(Array) && result.empty?)
-      @file_system.warning "No data was found in GitHub for #{@repo}. Is that what you expected?"
+      return JSON.parse(stdout)
     end
-    result
   end
 end

data/lib/jirametrics/html/cumulative_flow_diagram.erb

@@ -67,7 +67,7 @@ if (!Chart.Tooltip.positioners.legendItem) {
         const endX   = chart.scales.x.getPixelForValue(new Date(win.end_date).getTime());
 
         // Draw hatched slices over the correction window.
-        // For stacked line charts, PointElement has no .base — derive the band bottom from the
+        // For stacked line charts, PointElement has no .base - derive the band bottom from the
         // dataset directly below in the visual stack (dataset_index - 1, since datasets are
         // stored reversed), or chart.chartArea.bottom for the lowest dataset.
         // Use a trapezoid clip path per slice so hatching stays within the actual band boundary
@@ -330,7 +330,7 @@ if (!Chart.Tooltip.positioners.legendItem) {
         const parent = canvas.parentNode;
         if (getComputedStyle(parent).position === 'static') parent.style.position = 'relative';
         // Read canvas.offsetTop/Left after parent is positioned so they are
-        // relative to parent — this accounts for the label/checkbox above the
+        // relative to parent - this accounts for the label/checkbox above the
         // canvas that would otherwise shift the overlay upward.
         const overlay = document.createElement('canvas');
         overlay.width  = canvas.width;
@@ -426,7 +426,7 @@ if (!Chart.Tooltip.positioners.legendItem) {
         const fm = chart._flowMetrics;
         if (!fm) return;
         drawTrendLines(chart, fm);
-        // Triangle is on the overlay canvas — no drawing needed here.
+        // Triangle is on the overlay canvas - no drawing needed here.
       }
     };
   })();

data/lib/jirametrics/html/index.css

@@ -228,7 +228,7 @@ div.child_issue {
   padding: 0.5em;
 }
 
-/* Dark CSS variables — shared by the media query and the forced dark theme */
+/* Dark CSS variables - shared by the media query and the forced dark theme */
 html[data-theme="dark"] {
   --warning-banner: #9F2B00;
   --non-working-days-color: #2f2f2f;
@@ -240,7 +240,7 @@ html[data-theme="dark"] {
   --grid-line-color: #424242;
   --expedited-color: #E69F00;        /* Okabe-Ito orange for dark bg */
   --blocked-color: #E69F00;          /* Okabe-Ito orange for dark bg */
-  --stalled-color: #F0E442;          /* Okabe-Ito yellow — distinct from blocked */
+  --stalled-color: #F0E442;          /* Okabe-Ito yellow - distinct from blocked */
   --wip-chart-active-color: #56B4E9; /* sky blue for dark bg */
   --status-category-inprogress-color: #56B4E9;  /* sky blue for dark bg */
   --status-category-done-color: #2DCB9A;         /* lighter bluish green for dark bg */
@@ -284,7 +284,7 @@ html[data-theme="dark"] {
   }
 }
 
-/* Force light mode — overrides the dark media query when user explicitly picks light */
+/* Force light mode - overrides the dark media query when user explicitly picks light */
 html[data-theme="light"] {
   --warning-banner: yellow;
   --non-working-days-color: #F0F0F0;
@@ -380,7 +380,7 @@ html[data-theme="light"] {
 
     --expedited-color: #E69F00;        /* Okabe-Ito orange for dark bg */
     --blocked-color: #E69F00;          /* Okabe-Ito orange for dark bg */
-    --stalled-color: #F0E442;          /* Okabe-Ito yellow — distinct from blocked */
+    --stalled-color: #F0E442;          /* Okabe-Ito yellow - distinct from blocked */
     --dead-color: black;
     --wip-chart-active-color: #56B4E9; /* sky blue for dark bg */
 

data/lib/jirametrics/issue.rb

@@ -177,27 +177,8 @@ class Issue
   end
 
   def find_or_create_status id:, name:
-    status = board.possible_statuses.find_by_id(id)
-
-    unless status
-      # Have to pull this list before the call to fabricate or else the warning will incorrectly
-      # list this status as one it actually found
-      found_statuses = board.possible_statuses.to_s
-
-      status = board.possible_statuses.fabricate_status_for id: id, name: name
-
-      message = +'The history for issue '
-      message << key
-      message << ' references the status ('
-      message << "#{name.inspect}:#{id.inspect}"
-      message << ') that can\'t be found. We are guessing that this belongs to the '
-      message << status.category.to_s
-      message << ' status category but that may be wrong. See https://jirametrics.org/faq/#q1 for more '
-      message << 'details on defining statuses.'
-      board.project_config.file_system.warning message, more: "The statuses we did find are: #{found_statuses}"
-    end
-
-    status
+    board.possible_statuses.find_by_id(id) ||
+      board.possible_statuses.fabricate_status_for(id: id, name: name, example_issue_key: key)
   end
 
   def first_status_change_after_created
@@ -831,7 +812,7 @@ class Issue
     else
       # Otherwise, we look at what the first one had changed away from.
       first_status = first_change.old_value
-      # old_value_id should never be nil — a status change must have a 'from' id — but Jira has
+      # old_value_id should never be nil - a status change must have a 'from' id - but Jira has
       # been seen in production omitting the 'from' field entirely. Fall back to 0 so the
       # downstream fabricate/warn path handles it rather than crashing.
       first_status_id = first_change.old_value_id || 0

data/lib/jirametrics/jira_gateway.rb

@@ -71,8 +71,20 @@ class JiraGateway
             'Jira account may have been deactivated due to inactivity. Check your Jira subscription ' \
             'and try again later.'
     end
-    raise "Failed call with exit status #{status.exitstatus}. " \
-      "See #{@file_system.logfile_name} for details"
+    raise "#{failure_summary(status: status, stderr: stderr)}. See #{@file_system.logfile_name} for details"
+  end
+
+  # Turn curl's opaque exit code into something self-describing: prefer the HTTP status Jira
+  # returned, then curl's own error text (e.g. "Could not resolve host"), falling back to the exit
+  # code only when neither is present.
+  def failure_summary status:, stderr:
+    http_status = stderr[/returned error: (\d{3})/, 1]
+    return "Jira returned HTTP #{http_status}" if http_status
+
+    curl_message = stderr[/curl: \(\d+\) (.+)/, 1]
+    return "Jira call failed: #{curl_message.strip}" if curl_message
+
+    "Failed call with exit status #{status.exitstatus}"
   end
 
   def capture3 command, stdin_data:
@@ -95,6 +107,21 @@ class JiraGateway
     exec_and_parse_response command: command, stdin_data: nil
   end
 
+  VerifyResult = Data.define(:ok, :url, :message)
+
+  # Confirm that our credentials actually authenticate against Jira. We deliberately hit /myself,
+  # which requires authentication on every Jira edition (anonymous callers get a 401). An endpoint
+  # that also answers anonymously would happily "succeed" with bad credentials, which defeats the
+  # whole point. Cloud speaks v3, Server/Data Center speaks v2. Returns a VerifyResult rather than
+  # raising so the caller can report on every configured connection and set its own exit status.
+  def verify_connection
+    json = call_url relative_url: "/rest/api/#{cloud? ? 3 : 2}/myself"
+    user = json['displayName'] || json['name'] || json['emailAddress'] || 'unknown user'
+    VerifyResult.new(ok: true, url: @jira_url, message: "Verified #{@jira_url} (authenticated as #{user})")
+  rescue StandardError => e
+    VerifyResult.new(ok: false, url: @jira_url, message: "Could not authenticate to #{@jira_url}: #{e.message}")
+  end
+
   def parse_response command:, result:
     begin
       json = JSON.parse(result)

data/lib/jirametrics/mcp_server.rb

@@ -461,7 +461,7 @@ class McpServer
     description 'Aggregates the time issues spend in each status or column, ranked by average days. ' \
                 'Useful for identifying bottlenecks. Before calling this tool, always ask the user ' \
                 'which issues they want to include: aging (in progress), completed, not yet started, ' \
-                'or all. Do not assume — the answer changes the result significantly.'
+                'or all. Do not assume - the answer changes the result significantly.'
 
     input_schema(
       type: 'object',

data/lib/jirametrics/project_config.rb

@@ -56,6 +56,55 @@ class ProjectConfig
     anonymize_data if @anonymizer_needed
 
     @file_configs.each(&:run)
+
+    # By this point the charts have walked the issue histories, so every deleted status has already
+    # been fabricated lazily. Just report them. (The mcp path has no chart phase, so it resolves them
+    # explicitly before reporting.)
+    report_fabricated_statuses
+  end
+
+  # Walk every issue's status history so that any status that no longer exists in Jira gets fabricated
+  # now. Fabrication is otherwise lazy (it happens the first time a status is touched, which for some
+  # code paths is mid-render), so this gives us a single deterministic point where we know they all
+  # exist before we report them.
+  def resolve_all_status_changes
+    issues.each do |issue|
+      issue.status_changes.each do |change|
+        issue.find_or_create_status id: change.value_id, name: change.value
+      end
+    end
+  end
+
+  # Print one consolidated warning covering every status we had to fabricate (a status that an issue
+  # passed through but that no longer exists in Jira). It fires often -- any workflow rework leaves
+  # these behind -- so we say the explanation once and hand over a single ready-to-paste block of
+  # mappings rather than one repetitive paragraph per status.
+  def report_fabricated_statuses
+    statuses = possible_statuses.fabricated_statuses
+    return if statuses.empty? || @fabricated_statuses_reported
+
+    @fabricated_statuses_reported = true
+
+    width = statuses.map { |status| "'#{status.name}:#{status.id}'".length }.max
+    mappings = statuses.map do |status|
+      "      #{"'#{status.name}:#{status.id}'".ljust(width)} => '#{status.category.name}',"
+    end.join("\n")
+
+    example_key = possible_statuses.example_issue_key
+    info_line =
+      if example_key
+        "\nRun `jirametrics info #{example_key}` on an affected issue to see how it moved through its workflow."
+      else
+        ''
+      end
+
+    file_system.warning(
+      'Some statuses in your issue history no longer exist in Jira (they were probably deleted). ' \
+      "We've guessed each one's category from its name. If a guess is right the mapping just confirms " \
+      'it and silences this warning; if it is wrong, change the category. Add these to your ' \
+      "config's status category mappings; with standard_project that's:\n" \
+      "    status_category_mappings: {\n#{mappings}\n    }\n#{info_line}"
+    )
   end
 
   def load_settings

data/lib/jirametrics/status_collection.rb

@@ -4,11 +4,13 @@ class StatusNotFoundError < StandardError
 end
 
 class StatusCollection
-  attr_reader :historical_status_mappings
+  attr_reader :historical_status_mappings, :fabricated_statuses, :example_issue_key
 
   def initialize
     @list = []
     @historical_status_mappings = {} # 'name:id' => category
+    @fabricated_statuses = []
+    @example_issue_key = nil
   end
 
   # Return the status matching this id or nil if it can't be found.
@@ -88,9 +90,10 @@ class StatusCollection
     "StatusCollection#{self}"
   end
 
-  def fabricate_status_for id:, name:
+  def fabricate_status_for id:, name:, example_issue_key: nil
+    @example_issue_key ||= example_issue_key
     category = @historical_status_mappings["#{name.inspect}:#{id.inspect}"]
-    category = in_progress_category if category.nil?
+    category = guess_category_by_name(name) if category.nil?
 
     status = Status.new(
       name: name,
@@ -101,11 +104,32 @@ class StatusCollection
       artificial: true
     )
     @list << status
+    @fabricated_statuses << status
     status
   end
 
   private
 
+  # Guess the category of a deleted status from its name rather than always assuming In Progress. In
+  # English, "To Do"/"New"/"Backlog" are almost certainly To Do and "Done"/"Closed"/"Cancelled" are
+  # almost certainly Done; everything else we treat as In Progress. It's only a guess -- the user
+  # should still map anything that matters -- but it beats defaulting every deleted status to In
+  # Progress. Falls back to In Progress if the board has no status of the guessed category to borrow.
+  def guess_category_by_name name
+    normalized = name.to_s.downcase
+    todo = category_matching(:new?)
+    return todo if todo && normalized.match?(/\b(to.?do|new|backlog)\b/)
+
+    done = category_matching(:done?)
+    return done if done && normalized.match?(/\b(done|closed|cancell?ed)\b/)
+
+    in_progress_category
+  end
+
+  def category_matching predicate
+    find { |status| status.category.public_send(predicate) }&.category
+  end
+
   # Return the in-progress category or raise an error if we can't find one.
   def in_progress_category
     first_in_progress_status = find { |s| s.category.indeterminate? }

data/lib/jirametrics/wip_by_column_chart.rb

@@ -18,7 +18,7 @@ class WipByColumnChart < ChartBase
       <p>
         Each row on the Y axis is a WIP level (the number of items in that column at the same time).
         Each column on the X axis is a board column.
-        The horizontal bars show what percentage of the total time that column spent at that WIP level —
+        The horizontal bars show what percentage of the total time that column spent at that WIP level -
         a wider bar means more time was spent there.
       </p>
       <p>
@@ -136,7 +136,7 @@ class WipByColumnChart < ChartBase
 
       max = @wip_limits[i]['max']
       if max.nil?
-        "Add a WIP limit to column '#{name}' — suggested maximum: #{rec}"
+        "Add a WIP limit to column '#{name}' - suggested maximum: #{rec}"
       elsif rec < max
         "Lower the WIP limit for '#{name}' from #{max} to #{rec}"
       elsif rec > max
@@ -267,7 +267,7 @@ class WipByColumnChart < ChartBase
   end
 
   # Move the issue out of its old column and into new_col, keeping wip_counts and current_column in
-  # sync. A nil column means the issue isn't on the board — ie entering or leaving WIP.
+  # sync. A nil column means the issue isn't on the board - ie entering or leaving WIP.
   def apply_event wip_counts, current_column, issue, new_col
     old_col = current_column[issue]
     wip_counts[old_col] -= 1 unless old_col.nil?

data/lib/jirametrics.rb

@@ -46,6 +46,23 @@ class JiraMetrics < Thor
     Exporter.instance.export(name_filter: options[:name] || '*')
   end
 
+  option :config
+  option :name
+  desc 'verify', 'Check that JiraMetrics can authenticate to Jira, without downloading anything'
+  def verify
+    load_config options[:config]
+    results = Exporter.instance.verify_jira_connections(name_filter: options[:name] || '*')
+    exit 1 if results.empty? || results.any? { |result| !result.ok }
+  end
+
+  option :config
+  option :name
+  desc 'boards', "Show a board's columns and statuses, to help choose cycletime start/stop points"
+  def boards board_id = nil
+    load_config options[:config]
+    exit 1 unless Exporter.instance.boards(board_id: board_id, name_filter: options[:name])
+  end
+
   option :config
   desc 'info', 'Dump information about one issue'
   def info key
@@ -63,7 +80,9 @@ class JiraMetrics < Thor
     original_stdout = $stdout.dup
     $stdout.reopen($stderr)
 
-    load_config options[:config]
+    # Log to a separate file so that starting the MCP server doesn't truncate jirametrics.log, which
+    # someone may be relying on to debug a preceding export run.
+    load_config options[:config], logfile_name: 'jirametrics-mcp.log'
     require 'jirametrics/mcp_server'
 
     Exporter.instance.file_system.log_only = true
@@ -78,6 +97,10 @@ class JiraMetrics < Thor
         today: project.time_range.end.to_date,
         end_time: project.time_range.end
       }
+      # Fabrication is lazy, so force every historical status to resolve now and then emit the single
+      # consolidated warning into jirametrics-mcp.log (file_system is log_only here).
+      project.resolve_all_status_changes
+      project.report_fabricated_statuses
     rescue StandardError => e
       if e.message.start_with? 'This is an aggregated project'
         names = project.aggregate_project_names
@@ -122,7 +145,7 @@ class JiraMetrics < Thor
   at_exit { JiraMetrics.log_uncaught_exception $ERROR_INFO }
 
   no_commands do
-    def load_config config_file, file_system: FileSystem.new
+    def load_config config_file, logfile_name: nil, file_system: FileSystem.new
       config_file = './config.rb' if config_file.nil?
 
       if file_system.file_exist? config_file
@@ -135,6 +158,10 @@ class JiraMetrics < Thor
       end
 
       require_rel 'jirametrics'
+      # Set only after the require above, so Exporter is defined. The config file we load below calls
+      # Exporter.configure, which opens this log; the MCP server passes its own name so it doesn't
+      # truncate jirametrics.log.
+      Exporter.logfile_name = logfile_name if logfile_name
       load config_file
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '3.0'
+  version: '3.1'
 platform: ruby
 authors:
 - Mike Bowler