jirametrics 2.22 → 2.27

data/lib/jirametrics/mcp_server.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'mcp/server/transports/stdio_transport'
+
+class McpServer
+  def initialize projects:, timezone_offset: '+00:00'
+    @projects = projects
+    @timezone_offset = timezone_offset
+  end
+
+  def run
+    server = MCP::Server.new(
+      name: 'jirametrics',
+      version: Gem.loaded_specs['jirametrics']&.version&.to_s || '0.0.0',
+      tools: [AgingWorkTool, CompletedWorkTool, NotYetStartedTool],
+      server_context: { projects: @projects, timezone_offset: @timezone_offset }
+    )
+
+    transport = MCP::Server::Transports::StdioTransport.new(server)
+    transport.open
+  end
+
+  HISTORY_FILTER_SCHEMA = {
+    history_field: {
+      type: 'string',
+      description: 'When combined with history_value, only return issues where this field ever had that value ' \
+                   '(e.g. "priority", "status"). Both history_field and history_value must be provided together.'
+    },
+    history_value: {
+      type: 'string',
+      description: 'The value to look for in the change history of history_field (e.g. "Highest", "Done").'
+    },
+    ever_blocked: {
+      type: 'boolean',
+      description: 'When true, only return issues that were ever blocked. Blocked includes flagged items, ' \
+                   'issues in blocked statuses, and blocking issue links.'
+    },
+    ever_stalled: {
+      type: 'boolean',
+      description: 'When true, only return issues that were ever stalled. Stalled means the issue sat ' \
+                   'inactive for longer than the stalled threshold, or entered a stalled status.'
+    },
+    currently_blocked: {
+      type: 'boolean',
+      description: 'When true, only return issues that are currently blocked (as of the data end date).'
+    },
+    currently_stalled: {
+      type: 'boolean',
+      description: 'When true, only return issues that are currently stalled (as of the data end date).'
+    }
+  }.freeze
+
+  def self.flow_efficiency_percent issue, end_time
+    active_time, total_time = issue.flow_efficiency_numbers(end_time: end_time)
+    total_time.positive? ? (active_time / total_time * 100).round(1) : nil
+  end
+
+  def self.matches_blocked_stalled?(bsc, ever_blocked, ever_stalled, currently_blocked, currently_stalled)
+    return false if ever_blocked && bsc.none?(&:blocked?)
+    return false if ever_stalled && bsc.none?(&:stalled?)
+    return false if currently_blocked && !bsc.last&.blocked?
+    return false if currently_stalled && !bsc.last&.stalled?
+
+    true
+  end
+
+  def self.matches_history?(issue, end_time, history_field, history_value,
+                            ever_blocked, ever_stalled, currently_blocked, currently_stalled)
+    return false if history_field && history_value &&
+                    issue.changes.none? { |c| c.field == history_field && c.value == history_value }
+
+    if ever_blocked || ever_stalled || currently_blocked || currently_stalled
+      bsc = issue.blocked_stalled_changes(end_time: end_time)
+      return false unless matches_blocked_stalled?(bsc, ever_blocked, ever_stalled,
+                                                   currently_blocked, currently_stalled)
+    end
+
+    true
+  end
+
+  class AgingWorkTool < MCP::Tool
+    tool_name 'aging_work'
+    description 'Returns all issues that have been started but not yet completed (work in progress), ' \
+                'sorted from oldest to newest. Age is the number of days since the issue was started.'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        min_age_days: {
+          type: 'integer',
+          description: 'Only return issues at least this many days old. Omit to return all ages.'
+        },
+        project: {
+          type: 'string',
+          description: 'Only return issues from this project name. Omit to return all projects.'
+        },
+        **HISTORY_FILTER_SCHEMA
+      }
+    )
+
+    def self.call(server_context:, min_age_days: nil, project: nil,
+                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil)
+      rows = []
+
+      server_context[:projects].each do |project_name, project_data|
+        next if project && project_name != project
+
+        today = project_data[:today]
+        project_data[:issues].each do |issue|
+          started, stopped = issue.started_stopped_times
+          next unless started && !stopped
+
+          age = (today - started.to_date).to_i + 1
+          next if min_age_days && age < min_age_days
+          unless McpServer.matches_history?(issue, project_data[:end_time],
+                                            history_field, history_value, ever_blocked, ever_stalled,
+                                            currently_blocked, currently_stalled)
+            next
+          end
+
+          rows << {
+            key: issue.key,
+            summary: issue.summary,
+            status: issue.status.name,
+            type: issue.type,
+            age_days: age,
+            flow_efficiency: McpServer.flow_efficiency_percent(issue, project_data[:end_time]),
+            project: project_name
+          }
+        end
+      end
+
+      rows.sort_by! { |r| -r[:age_days] }
+
+      if rows.empty?
+        text = 'No aging work found.'
+      else
+        lines = rows.map do |r|
+          fe = r[:flow_efficiency] ? " | FE: #{r[:flow_efficiency]}%" : ''
+          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:status]} | Age: #{r[:age_days]}d#{fe} | #{r[:summary]}"
+        end
+        text = lines.join("\n")
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+  end
+
+  class CompletedWorkTool < MCP::Tool
+    tool_name 'completed_work'
+    description 'Returns issues that have been completed, sorted most recently completed first. ' \
+                'Includes cycle time (days from start to completion).'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        days_back: {
+          type: 'integer',
+          description: 'Only return issues completed within this many days of the data end date. Omit to return all.'
+        },
+        project: {
+          type: 'string',
+          description: 'Only return issues from this project name. Omit to return all projects.'
+        },
+        completed_status: {
+          type: 'string',
+          description: 'Only return issues whose status at completion matches this value (e.g. "Cancelled", "Done").'
+        },
+        completed_resolution: {
+          type: 'string',
+          description: 'Only return issues whose resolution at completion matches this value (e.g. "Won\'t Do").'
+        },
+        **HISTORY_FILTER_SCHEMA
+      }
+    )
+
+    def self.build_row issue, project_name, started, stopped, cutoff, completed_status, completed_resolution,
+                       end_time, history_field, history_value, ever_blocked, ever_stalled,
+                       currently_blocked, currently_stalled
+      completed_date = stopped.to_date
+      return nil if cutoff && completed_date < cutoff
+
+      status_at_done, resolution_at_done = issue.status_resolution_at_done
+      return nil if completed_status && status_at_done&.name != completed_status
+      return nil if completed_resolution && completed_resolution != resolution_at_done
+      return nil unless McpServer.matches_history?(issue, end_time,
+                                                   history_field, history_value, ever_blocked, ever_stalled,
+                                                   currently_blocked, currently_stalled)
+
+      cycle_time = started ? (completed_date - started.to_date).to_i + 1 : nil
+      {
+        key: issue.key,
+        summary: issue.summary,
+        type: issue.type,
+        completed_date: completed_date,
+        cycle_time_days: cycle_time,
+        flow_efficiency: McpServer.flow_efficiency_percent(issue, stopped),
+        status_at_done: status_at_done&.name,
+        resolution_at_done: resolution_at_done,
+        project: project_name
+      }
+    end
+
+    def self.call(server_context:, days_back: nil, project: nil,
+                  completed_status: nil, completed_resolution: nil,
+                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil)
+      rows = []
+
+      server_context[:projects].each do |project_name, project_data|
+        next if project && project_name != project
+
+        today = project_data[:today]
+        cutoff = today - days_back if days_back
+
+        project_data[:issues].each do |issue|
+          started, stopped = issue.started_stopped_times
+          next unless stopped
+
+          row = build_row(issue, project_name, started, stopped, cutoff, completed_status, completed_resolution,
+                          project_data[:end_time], history_field, history_value, ever_blocked, ever_stalled,
+                          currently_blocked, currently_stalled)
+          rows << row if row
+        end
+      end
+
+      rows.sort_by! { |r| -r[:completed_date].to_time.to_i }
+
+      if rows.empty?
+        text = 'No completed work found.'
+      else
+        lines = rows.map do |r|
+          ct = r[:cycle_time_days] ? "#{r[:cycle_time_days]}d" : 'unknown'
+          fe = r[:flow_efficiency] ? " | FE: #{r[:flow_efficiency]}%" : ''
+          completion = [r[:status_at_done], r[:resolution_at_done]].compact.join(' / ')
+          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:completed_date]} | " \
+            "Cycle time: #{ct}#{fe} | #{completion} | #{r[:summary]}"
+        end
+        text = lines.join("\n")
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+  end
+
+  class NotYetStartedTool < MCP::Tool
+    tool_name 'not_yet_started'
+    description 'Returns issues that have not yet been started (backlog items), sorted by creation date oldest first.'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        project: {
+          type: 'string',
+          description: 'Only return issues from this project name. Omit to return all projects.'
+        },
+        **HISTORY_FILTER_SCHEMA
+      }
+    )
+
+    def self.call(server_context:, project: nil,
+                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil)
+      rows = []
+
+      server_context[:projects].each do |project_name, project_data|
+        next if project && project_name != project
+
+        project_data[:issues].each do |issue|
+          started, stopped = issue.started_stopped_times
+          next if started || stopped
+          unless McpServer.matches_history?(issue, project_data[:end_time],
+                                            history_field, history_value, ever_blocked, ever_stalled,
+                                            currently_blocked, currently_stalled)
+            next
+          end
+
+          rows << {
+            key: issue.key,
+            summary: issue.summary,
+            status: issue.status.name,
+            type: issue.type,
+            created: issue.created.to_date,
+            project: project_name
+          }
+        end
+      end
+
+      rows.sort_by! { |r| r[:created] }
+
+      if rows.empty?
+        text = 'No unstarted work found.'
+      else
+        lines = rows.map do |r|
+          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:status]} | Created: #{r[:created]} | #{r[:summary]}"
+        end
+        text = lines.join("\n")
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+  end
+end

data/lib/jirametrics/project_config.rb

@@ -6,7 +6,7 @@ require 'jirametrics/status_collection'
 class ProjectConfig
   attr_reader :target_path, :jira_config, :all_boards, :possible_statuses,
     :download_config, :file_configs, :exporter, :data_version, :name, :board_configs,
-    :settings, :aggregate_config, :discarded_changes_data, :users
+    :settings, :aggregate_config, :discarded_changes_data, :users, :fix_versions
   attr_accessor :time_range, :jira_url, :id
 
   def initialize exporter:, jira_config:, block:, target_path: '.', name: '', id: nil
@@ -23,6 +23,7 @@ class ProjectConfig
     @settings = load_settings
     @id = id
     @has_loaded_data = false
+    @fix_versions = []
   end
 
   def evaluate_next_level
@@ -40,17 +41,20 @@ class ProjectConfig
     @id = guess_project_id
     load_project_metadata
     load_sprints
+    load_fix_versions
     load_users
+    resolve_blocked_stalled_status_settings
   end
 
   def run load_only: false
     return if @exporter.downloading?
 
     load_data unless aggregated_project?
-    anonymize_data if @anonymizer_needed
 
     return if load_only
 
+    anonymize_data if @anonymizer_needed
+
     @file_configs.each do |file_config|
       file_config.run
     end
@@ -67,7 +71,10 @@ class ProjectConfig
       file_system.deprecated message: 'stalled color should be set via css now', date: '2024-05-03'
     end
 
-    settings
+    settings['blocked_statuses'] = StatusCollection.new
+    settings['stalled_statuses'] = StatusCollection.new
+
+    stringify_keys(settings)
   end
 
   def guess_project_id
@@ -143,6 +150,17 @@ class ProjectConfig
     @file_prefix
   end
 
+  def validate_discard_status status_name
+    return if status_name == :backlog
+    return if possible_statuses.empty? # not yet downloaded; skip validation
+
+    found = possible_statuses.find_all_by_name status_name
+    return unless found.empty?
+
+    raise "discard_changes_before: Status #{status_name.inspect} not found. " \
+      "Possible statuses are: #{possible_statuses}"
+  end
+
   def raise_if_prefix_already_used prefix
     @exporter.project_configs.each do |project|
       next unless project.get_file_prefix(raise_if_not_set: false) == prefix && project.target_path == target_path
@@ -267,9 +285,16 @@ class ProjectConfig
   end
 
   def load_board board_id:, filename:
-    board = Board.new(
-      raw: file_system.load_json(filename), possible_statuses: @possible_statuses
-    )
+    raw = file_system.load_json(filename)
+
+    features_filename = File.join(@target_path, "#{get_file_prefix}_board_#{board_id}_features.json")
+    features = if file_system.file_exist?(features_filename)
+                 BoardFeature.from_raw(file_system.load_json(features_filename))
+               else
+                 []
+               end
+
+    board = Board.new(raw: raw, possible_statuses: @possible_statuses, features: features)
     board.project_config = self
     @all_boards[board_id] = board
   end
@@ -326,6 +351,13 @@ class ProjectConfig
     end
   end
 
+  def load_fix_versions
+    filename = File.join(@target_path, "#{get_file_prefix}_fix_versions.json")
+    return unless file_system.file_exist?(filename)
+
+    @fix_versions = file_system.load_json(filename).map { |raw| FixVersion.new(raw) }
+  end
+
   def load_project_metadata
     filename = File.join @target_path, "#{get_file_prefix}_meta.json"
     json = file_system.load_json(filename)
@@ -362,6 +394,19 @@ class ProjectConfig
     json.each { |user_data| @users << User.new(raw: user_data) }
   end
 
+  def attach_github_prs
+    filename = File.join(@target_path, "#{get_file_prefix}_github_prs.json")
+    return unless File.exist?(filename)
+
+    prs_by_issue_key = Hash.new { |h, k| h[k] = [] }
+    file_system.load_json(filename).each do |raw|
+      pr = PullRequest.new(raw: raw)
+      pr.issue_keys.each { |key| prs_by_issue_key[key] << pr }
+    end
+
+    @issues.each { |issue| issue.github_prs = prs_by_issue_key[issue.key] }
+  end
+
   def atlassian_document_format
     @atlassian_document_format ||= AtlassianDocumentFormat.new(
       users: @users, timezone_offset: exporter.timezone_offset
@@ -444,6 +489,7 @@ class ProjectConfig
       # attached them in the appropriate places, remove any that aren't part of that initial set.
       issues.reject! { |i| !i.in_initial_query? } # rubocop:disable Style/InverseMethods
       @issues = issues
+      attach_github_prs
     end
 
     @issues
@@ -563,6 +609,8 @@ class ProjectConfig
     if status_becomes
       status_becomes = [status_becomes] unless status_becomes.is_a? Array
 
+      status_becomes.each { |status_name| validate_discard_status status_name }
+
       block = lambda do |issue|
         trigger_statuses = status_becomes.collect do |status_name|
           if status_name == :backlog
@@ -588,7 +636,7 @@ class ProjectConfig
       cutoff_time = block.call(issue)
       next if cutoff_time.nil?
 
-      original_start_time = issue.board.cycletime.started_stopped_times(issue).first
+      original_start_time = issue.started_stopped_times.first
       next if original_start_time.nil?
 
       issue.discard_changes_before cutoff_time
@@ -606,4 +654,29 @@ class ProjectConfig
 
     cycletimes_touched.each { |c| c.flush_cache }
   end
+
+  def stringify_keys value
+    case value
+    when Hash then value.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
+    when Array then value.map { |v| stringify_keys(v) }
+    else value
+    end
+  end
+
+  def resolve_blocked_stalled_status_settings
+    %w[blocked_statuses stalled_statuses].each do |key|
+      next if @settings[key].is_a?(StatusCollection)
+
+      collection = StatusCollection.new
+      @settings[key].each do |identifier|
+        statuses = @possible_statuses.find_all_by_name(identifier)
+        if statuses.empty?
+          file_system.warning "Status #{identifier.inspect} in #{key} not found. Ignoring."
+        else
+          statuses.each { |status| collection << status }
+        end
+      end
+      @settings[key] = collection
+    end
+  end
 end

data/lib/jirametrics/pull_request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'jirametrics/pull_request_review'
+
+class PullRequest
+  attr_reader :raw
+
+  def initialize raw:
+    @raw = raw
+  end
+
+  def number     = @raw['number']
+  def repo       = @raw['repo']
+  def url        = @raw['url']
+  def title      = @raw['title']
+  def branch     = @raw['branch']
+  def state      = @raw['state']
+  def issue_keys = @raw['issue_keys']
+
+  def opened_at = Time.parse(@raw['opened_at'])
+  def closed_at = @raw['closed_at'] ? Time.parse(@raw['closed_at']) : nil
+  def merged_at = @raw['merged_at'] ? Time.parse(@raw['merged_at']) : nil
+
+  def reviews       = (@raw['reviews'] || []).map { |r| PullRequestReview.new(raw: r) }
+  def additions     = @raw['additions']
+  def deletions     = @raw['deletions']
+  def changed_files = @raw['changed_files']
+  def lines_changed = (additions || 0) + (deletions || 0)
+end

data/lib/jirametrics/pull_request_cycle_time_histogram.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class PullRequestCycleTimeHistogram < TimeBasedHistogram
+  def initialize block
+    super()
+
+    @cycletime_unit = :days
+    @x_axis_title = 'Cycle time in days'
+
+    header_text 'PR Histogram'
+    description_text <<-HTML
+      <div class="p">
+        This cycletime Histogram shows how many pull requests completed in a certain timeframe. This can be
+        useful for determining how many different types of work are flowing through, based on the
+        lengths of time they take.
+      </div>
+    HTML
+
+    init_configuration_block(block) do
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
+      end
+    end
+  end
+
+  def cycletime_unit unit
+    unless %i[minutes hours days].include?(unit)
+      raise ArgumentError, "cycletime_unit must be :minutes, :hours, or :days, got #{unit.inspect}"
+    end
+
+    @cycletime_unit = unit
+    @x_axis_title = "Cycle time in #{unit}"
+  end
+
+  def all_items
+    result = []
+    issues.each do |issue|
+      next unless issue.github_prs
+
+      issue.github_prs.each do |pr|
+        next unless pr.closed_at
+
+        result << pr
+      end
+    end
+    result.uniq
+  end
+
+  def value_for_item item
+    divisor = { minutes: 60.0, hours: 3600.0, days: 86_400.0 }[@cycletime_unit]
+    ((item.closed_at - item.opened_at) / divisor).ceil
+  end
+
+  def label_cycletime value
+    case @cycletime_unit
+    when :minutes then label_minutes(value)
+    when :hours then label_hours(value)
+    when :days then label_days(value)
+    end
+  end
+
+  def title_for_item count:, value:
+    "#{count} PR#{'s' unless count == 1} closed in #{label_cycletime value}"
+  end
+
+  def sort_items items
+    items.sort_by(&:opened_at)
+  end
+
+  def label_for_item item, hint:
+    label = "#{item.number} #{item.title}"
+    label << hint if hint
+    label
+  end
+end

data/lib/jirametrics/pull_request_cycle_time_scatterplot.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'jirametrics/groupable_issue_chart'
+
+class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
+  def initialize block
+    super()
+
+    @cycletime_unit = :days
+    @y_axis_title = 'Cycle time in days'
+
+    header_text 'Pull Request (PR) Scatterplot'
+    description_text <<-HTML
+      <div class="p">
+        This graph shows the cycle time for all closed pull requests (time from opened to closed).
+      </div>
+      #{describe_non_working_days}
+    HTML
+
+    init_configuration_block(block) do
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
+      end
+    end
+  end
+
+  def cycletime_unit unit
+    unless %i[minutes hours days].include?(unit)
+      raise ArgumentError, "cycletime_unit must be :minutes, :hours, or :days, got #{unit.inspect}"
+    end
+
+    @cycletime_unit = unit
+    @y_axis_title = "Cycle time in #{unit}"
+  end
+
+  def all_items
+    result = []
+    issues.each do |issue|
+      issue.github_prs&.each do |pr|
+        result << pr if pr.closed_at
+      end
+    end
+    result
+  end
+
+  def x_value pull_request
+    pull_request.closed_at
+  end
+
+  def y_value pull_request
+    if @cycletime_unit == :days
+      tz = timezone_offset || '+00:00'
+      opened = pull_request.opened_at.getlocal(tz).to_date
+      closed = pull_request.closed_at.getlocal(tz).to_date
+      (closed - opened).to_i + 1
+    else
+      divisor = { minutes: 60, hours: 3600 }[@cycletime_unit]
+      ((pull_request.closed_at - pull_request.opened_at) / divisor).round
+    end
+  end
+
+  def label_cycletime value
+    case @cycletime_unit
+    when :minutes then label_minutes(value)
+    when :hours then label_hours(value)
+    when :days then label_days(value)
+    end
+  end
+
+  def title_value pull_request, rules: nil
+    age_label = label_cycletime y_value(pull_request)
+    keys = pull_request.issue_keys.join(', ')
+    "#{keys} | #{pull_request.title} | #{rules.label} | Age:#{age_label}#{lines_changed_text(pull_request)}"
+  end
+
+  def lines_changed_text pull_request
+    return '' unless pull_request.changed_files
+
+    additions = pull_request.additions || 0
+    deletions = pull_request.deletions || 0
+    text = +' | Lines changed: ['
+    text << "+#{to_human_readable additions}" unless additions.zero?
+    text << ' ' if additions != 0 && deletions != 0
+    text << "-#{to_human_readable deletions}" unless deletions.zero?
+    text << "], Files changed: #{to_human_readable pull_request.changed_files}"
+    text
+  end
+end

data/lib/jirametrics/pull_request_review.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'time'
+
+class PullRequestReview
+  def initialize raw:
+    @raw = raw
+  end
+
+  def author = @raw['author']
+  def state = @raw['state']
+  def submitted_at = Time.parse(@raw['submitted_at'])
+end

data/lib/jirametrics/raw_javascript.rb

@@ -10,4 +10,8 @@ class RawJavascript
   def to_json(*_args)
     @content
   end
+
+  def == other
+    other.is_a?(RawJavascript) && to_json == other.to_json
+  end
 end