jirametrics 2.31 → 3.1

data/lib/jirametrics/exporter.rb

@@ -6,11 +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'
-    logfile = File.open(logfile_name, 'w')
+    # 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
@@ -71,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
@@ -78,12 +262,7 @@ class Exporter
       project.evaluate_next_level
 
       project.run load_only: true
-      project.issues.each do |issue|
-        selected << [project, issue] if key == issue.key
-        issue.subtasks.each do |subtask|
-          selected << [project, subtask] if key == subtask.key
-        end
-      end
+      selected.concat matching_issues_in(project, key)
     rescue => e # rubocop:disable Style/RescueStandardError
       # This happens when we're attempting to load an aggregated project because it hasn't been
       # properly initialized. Since we don't care about aggregated projects, we just ignore it.
@@ -101,6 +280,17 @@ class Exporter
     end
   end
 
+  def matching_issues_in project, key
+    matches = []
+    project.issues.each do |issue|
+      matches << [project, issue] if key == issue.key
+      issue.subtasks.each do |subtask|
+        matches << [project, subtask] if key == subtask.key
+      end
+    end
+    matches
+  end
+
   def stitch stitch_file
     Stitcher.new(file_system: file_system).run(stitch_file: stitch_file)
   end
@@ -139,7 +329,8 @@ class Exporter
       @jira_config = file_system.load_json(filename, fail_on_error: false)
       raise "Unable to load Jira configuration file and cannot continue: #{filename.inspect}" if @jira_config.nil?
 
-      @jira_config['url'] = $1 if @jira_config['url'] =~ /^(.+)\/+$/
+      match = %r{^(?<base_url>.+)/+$}.match(@jira_config['url'])
+      @jira_config['url'] = match[:base_url] if match
     end
     @jira_config
   end
@@ -153,8 +344,8 @@ class Exporter
     unless args.empty?
       dates = []
       args.each do |arg|
-        if arg =~ /^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/
-          Date.parse($1).upto(Date.parse($2)).each { |date| dates << date }
+        if /^(?<from>\d{4}-\d{2}-\d{2})\.\.(?<to>\d{4}-\d{2}-\d{2})$/ =~ arg
+          Date.parse(from).upto(Date.parse(to)).each { |date| dates << date }
         else
           dates << Date.parse(arg)
         end

data/lib/jirametrics/file_config.rb

@@ -5,11 +5,12 @@ require 'csv'
 class FileConfig
   attr_reader :project_config, :issues
 
-  def initialize project_config:, block:, today: Date.today
+  def initialize project_config:, block:, today: Date.today, issues: nil
     @project_config = project_config
     @block = block
     @columns = nil
     @today = today
+    @issues = issues
   end
 
   def run
@@ -65,22 +66,28 @@ class FileConfig
   # most common usecase - the Team Dashboard from FocusedObjective.com. The rule for that one
   # is that all empty values in the first column should be at the bottom.
   def sort_output all_lines
-    all_lines.each_with_index.sort do |(a, a_idx), (b, b_idx)|
-      result = if a[0] == b[0]
-        a[1..] <=> b[1..]
-      elsif a[0].nil?
-        1
-      elsif b[0].nil?
-        -1
-      else
-        a[0] <=> b[0]
-      end
+    all_lines.each_with_index.sort do |(left, left_idx), (right, right_idx)|
+      result = compare_rows left, right
 
       # When objects aren't comparable, preserve original order for a stable sort.
-      result.nil? || result.zero? ? a_idx <=> b_idx : result
+      result.nil? || result.zero? ? left_idx <=> right_idx : result
     end.map(&:first)
   end
 
+  # Compare two rows by their first column, falling back to the remaining columns on a tie, and
+  # sorting nil first columns to the bottom.
+  def compare_rows left, right
+    if left[0] == right[0]
+      left[1..] <=> right[1..]
+    elsif left[0].nil?
+      1
+    elsif right[0].nil?
+      -1
+    else
+      left[0] <=> right[0]
+    end
+  end
+
   def columns &block
     assert_only_one_filetype_config_set
     @columns = ColumnsConfig.new file_config: self, block: block

data/lib/jirametrics/file_system.rb

@@ -2,6 +2,10 @@
 
 require 'json'
 
+# This is the stderr display/logging layer: it writes progress and log output straight to $stderr
+# (see the $stderr.print/.flush calls). That output isn't warnings, so $stderr.puts is intentional
+# throughout rather than warn.
+# rubocop:disable Style/StderrPuts
 class FileSystem
   attr_accessor :logfile, :logfile_name, :log_only
 
@@ -14,18 +18,14 @@ class FileSystem
   end
 
   # Effectively the same as File.read except it forces the encoding to UTF-8
-  def load filename, supress_deprecation: false
-    if filename.end_with?('.json') && !supress_deprecation
-      deprecated(message: 'call load_json instead', date: '2024-11-13')
-    end
-
+  def load filename
     File.read filename, encoding: 'UTF-8'
   end
 
   def load_json filename, fail_on_error: true
     return nil if fail_on_error == false && File.exist?(filename) == false
 
-    JSON.parse load(filename, supress_deprecation: true)
+    JSON.parse load(filename)
   end
 
   def save_json json:, filename:
@@ -70,7 +70,7 @@ class FileSystem
     # set up. Quick escape here so that we don't dump the error twice.
     return if logfile == $stdout
 
-    $stderr.puts message # rubocop:disable Style/StderrPuts
+    $stderr.puts message
   end
 
   def log_start message
@@ -98,21 +98,26 @@ class FileSystem
   def end_progress
     return if log_only
 
-    $stderr.puts '' # rubocop:disable Style/StderrPuts
+    $stderr.puts ''
   end
 
   # In some Jira instances, a sizeable portion of the JSON is made up of empty fields. I've seen
   # cases where this simple compression will drop the filesize by half.
   def compress node
     if node.is_a? Hash
-      node.reject! { |_key, value| value.nil? || (value.is_a?(Array) && value.empty?) }
+      node.reject! { |_key, value| prunable? value }
       node.each_value { |value| compress value }
     elsif node.is_a? Array
-      node.each { |a| compress a }
+      node.each { |element| compress element }
     end
     node
   end
 
+  # A value worth dropping from the compressed output: nothing there, or an empty array.
+  def prunable? value
+    value.nil? || (value.is_a?(Array) && value.empty?)
+  end
+
   def foreach root, &block
     Dir.foreach root, &block
   end
@@ -139,3 +144,4 @@ class FileSystem
     log text, also_write_to_stderr: true
   end
 end
+# rubocop:enable Style/StderrPuts

data/lib/jirametrics/flow_efficiency_calculator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Walks a stream of BlockedStalledChange entries and totals up the value-add (active) time between
+# issue_start and end_time. It's handed the already-computed stream and the resolved start/end so it
+# never reaches back through the issue's collaborators.
+#
+# Returns [value_add_seconds, total_seconds].
+class FlowEfficiencyCalculator
+  def initialize blocked_stalled_changes:, issue_start:, end_time:
+    @blocked_stalled_changes = blocked_stalled_changes
+    @issue_start = issue_start
+    @end_time = end_time
+  end
+
+  def calculate
+    @active_start = nil
+    @value_add_time = 0.0
+
+    @blocked_stalled_changes.each_with_index do |change, index|
+      break if change.time > @end_time
+
+      process change, index
+    end
+
+    close_final_active_period
+
+    [@value_add_time, @end_time - @issue_start]
+  end
+
+  def process change, index
+    if index.zero?
+      @active_start = change.time if change.active?
+      return
+    end
+
+    process_transition change
+  end
+
+  def process_transition change
+    # Already active and we just got another active.
+    return 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.
+      record_active_period ending_at: change.time
+      @active_start = nil
+    end
+  end
+
+  def record_active_period ending_at:
+    @value_add_time += ending_at - [@issue_start, @active_start].max
+  end
+
+  def close_final_active_period
+    return unless @active_start
+
+    change_delta = @end_time - [@issue_start, @active_start].max
+    @value_add_time += change_delta if change_delta.positive?
+  end
+end

data/lib/jirametrics/flow_efficiency_scatterplot.rb

@@ -7,7 +7,8 @@ class FlowEfficiencyScatterplot < ChartBase
 
   attr_accessor :possible_statuses
 
-  def initialize block
+  # Long only because of the inline description_text heredoc and one-time setup; splitting wouldn't help.
+  def initialize block # rubocop:disable Metrics/MethodLength
     super()
 
     header_text 'Flow Efficiency'
@@ -63,7 +64,8 @@ class FlowEfficiencyScatterplot < ChartBase
     end
 
     if data_sets.empty?
-      return "<h1 class='foldable'>#{@header_text}</h1><div>No data matched the selected criteria. Nothing to show.</div>"
+      return "<h1 class='foldable'>#{@header_text}</h1>" \
+        '<div>No data matched the selected criteria. Nothing to show.</div>'
     end
 
     wrap_and_render(binding, __FILE__)

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
@@ -139,14 +154,18 @@ class GithubGateway
       # fallback fetches the complete set rather than us caching a partial answer.
       next if commits['totalCount'] && commits['totalCount'] > nodes.size
 
-      messages_by_number[number] = nodes.flat_map do |node|
-        commit = node['commit'] || {}
-        [commit['messageHeadline'], commit['messageBody']].compact
-      end
+      messages_by_number[number] = commit_messages_from(nodes)
     end
     messages_by_number
   end
 
+  def commit_messages_from nodes
+    nodes.flat_map do |node|
+      commit = node['commit'] || {}
+      [commit['messageHeadline'], commit['messageBody']].compact
+    end
+  end
+
   def owner_and_name
     # @repo may be a full URL (https://github.com/owner/name.git) or an owner/name slug.
     @repo.sub(%r{\Ahttps?://[^/]+/}, '').delete_suffix('.git').split('/', 2)
@@ -173,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
@@ -195,6 +233,11 @@ 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
+        # 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.
+        # rubocop:disable Style/ArrayIntersect
         if attempts < MAX_RETRIES && TRANSIENT_ERROR_PATTERNS.any? { |pattern| stderr.include?(pattern) }
           delay = 2**attempts
           @file_system.log error_message
@@ -202,15 +245,12 @@ class GithubGateway
           sleep delay
           next
         end
-        @file_system.warning error_message
+        # rubocop:enable Style/ArrayIntersect
+        @file_system.warning error_message if warn_on_failure
         raise "GitHub CLI command failed for #{@repo}: #{stderr}"
       end
 
-      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?"
-      end
-      return result
+      return JSON.parse(stdout)
     end
   end
 end

data/lib/jirametrics/groupable_issue_chart.rb

@@ -4,6 +4,9 @@ require 'jirametrics/rules'
 require 'jirametrics/grouping_rules'
 
 module GroupableIssueChart
+  attr_accessor :issue_hints, :issue_periods
+  attr_reader :group_by_block
+
   def init_configuration_block user_provided_block, &default_block
     instance_eval(&user_provided_block)
     instance_eval(&default_block) unless @group_by_block

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.
       }
     };
   })();