jirametrics 2.26.1 → 2.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 960ce78e94ec2c7e87875bd0dc6db2c16b11cee0e4c4dd5a22d8bf3bab1c893d
-  data.tar.gz: f5b2d9aac4d9059654ad7a569d477b0b689c8d22f30760867aec9e13b3f1db61
+  metadata.gz: c87212eebf4e22145b8e66741174658bffc3cb1e47bd45bfe3f7590586a42200
+  data.tar.gz: 00fb6c4375e7e6858359fa754af42c697028198dedd2ae8100c98d0564f59db8
 SHA512:
-  metadata.gz: 727e2f5b3e57e937eacd05d868ff1f7a75e16210f0e46e75117a88e56287fb765238753710289d9fb2f09b38d6e940f47d0ae2689be313b1282238727ddae0eb
-  data.tar.gz: d60771157926c74a7ac45d12ea023eef1808b4ea027f8edd6fba6108a79b2f0df8bdb054bf58049cc8a3f3de44e4926dd0af0a40b95b25fb07ed1391d829418b
+  metadata.gz: aad3747a78dcf530df02244720c676632816a30688045d95c9a701ba946a5573f81a2e3955c5035e745fb197f5c6cff58491a63d35db68b3abf35817c78dc0b8
+  data.tar.gz: fcf17a8c2a4c91e4de45ff15150d1de9147c890d9e80354b490bec2b27fb17ef2b20e7bc6073c503e88fd0ad188c414002d8312500b22dd5207b043d3c253be7

data/lib/jirametrics/chart_base.rb

@@ -377,7 +377,7 @@ class ChartBase
   end
 
   def seam_start type = 'chart'
-    "\n<!-- seam-start | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->"
+    "\n<!-- seam-start | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->\n"
   end
 
   def seam_end type = 'chart'

data/lib/jirametrics/cumulative_flow_diagram.rb

@@ -69,6 +69,9 @@ class CumulativeFlowDiagram < ChartBase
         When the cursor is near the right edge and that point falls outside the visible date range,
         CT and TP cannot be calculated and are hidden; only WIP is shown.
       </div>
+      <div class="p">
+        See also: This article on [how to read a CFD](https://blog.mikebowler.ca/2026/03/27/cumulative-flow-diagram/).
+      </div>      
     HTML
     instance_eval(&block)
   end

data/lib/jirametrics/examples/aggregated_project.rb

@@ -10,7 +10,7 @@
 class Exporter
   def aggregated_project name:, project_names:, settings: {}
     project name: name do
-      puts name
+      file_system.log name
       file_prefix name
       self.settings.merge! stringify_keys(settings)
 

data/lib/jirametrics/examples/standard_project.rb

@@ -9,7 +9,7 @@ class Exporter
       show_experimental_charts: false, github_repos: nil
     exporter = self
     project name: name do
-      puts name
+      file_system.log name
       file_prefix file_prefix
 
       self.anonymize if anonymize
@@ -35,7 +35,7 @@ class Exporter
       download do
         self.rolling_date_count(rolling_date_count) if rolling_date_count
         self.no_earlier_than(no_earlier_than) if no_earlier_than
-        github_repo github_repos if github_repos
+        github_repo *github_repos if github_repos
       end
 
       issues.reject! do |issue|

data/lib/jirametrics/file_system.rb

@@ -3,13 +3,14 @@
 require 'json'
 
 class FileSystem
-  attr_accessor :logfile, :logfile_name
+  attr_accessor :logfile, :logfile_name, :log_only
 
   def initialize
     # In almost all cases, this will be immediately replaced in the Exporter
     # but if we fail before we get that far, this will at least let a useful
     # error show up on the console.
     @logfile = $stdout
+    @log_only = false
   end
 
   # Effectively the same as File.read except it forces the encoding to UTF-8
@@ -59,7 +60,7 @@ class FileSystem
 
     logfile.puts message
     logfile.puts more if more
-    return unless also_write_to_stderr
+    return if log_only || !also_write_to_stderr
 
     # Obscure edge-case where we're trying to log something before logging is even
     # set up. Quick escape here so that we don't dump the error twice.
@@ -70,23 +71,29 @@ class FileSystem
 
   def log_start message
     logfile.puts message
-    return if logfile == $stdout
+    return if log_only || logfile == $stdout
 
     $stderr.print message
     $stderr.flush
   end
 
   def start_progress
+    return if log_only
+
     $stderr.print '  '
     $stderr.flush
   end
 
   def progress_dot
+    return if log_only
+
     $stderr.print '.'
     $stderr.flush
   end
 
   def end_progress
+    return if log_only
+
     $stderr.puts '' # rubocop:disable Style/StderrPuts
   end
 

data/lib/jirametrics/github_gateway.rb

@@ -64,9 +64,10 @@ class GithubGateway
       raw_pr['body']
     ]
 
-    sources.compact
-           .flat_map { |s| s.scan(@issue_key_pattern) }
-           .uniq
+    keys = sources.compact.flat_map { |s| s.scan(@issue_key_pattern) }.uniq
+    return keys unless keys.empty?
+
+    commit_messages_for(raw_pr['number']).flat_map { |msg| msg.scan(@issue_key_pattern) }.uniq
   end
 
   def extract_reviews raw_reviews
@@ -83,11 +84,19 @@ class GithubGateway
 
   private
 
+  def commit_messages_for pr_number
+    args = ['pr', 'view', pr_number.to_s, '--json', 'commits', '--repo', @repo]
+    result = run_command(args)
+    (result['commits'] || []).flat_map do |commit|
+      [commit['messageHeadline'], commit['messageBody']].compact
+    end
+  end
+
   def build_issue_key_pattern
     return nil if @project_keys.empty?
 
     keys_pattern = @project_keys.map { |k| Regexp.escape(k) }.join('|')
-    Regexp.new("\\b(?:#{keys_pattern})-\\d+\\b")
+    Regexp.new("\\b(?:#{keys_pattern})-\\d+(?![A-Za-z0-9])")
   end
 
   def run_command args

data/lib/jirametrics/html/time_based_scatterplot.erb

@@ -28,15 +28,20 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
         max: "<%= (date_range.end + 1).to_s %>"
       },
       y: {
+        min: 0,
+        max: <%= (@highest_y_value * 1.1).ceil %>,
         scaleLabel: {
-          display: true,
-          min: 0,
-          max: <%= @highest_y_value %>
+          display: true
         },
         <%= render_axis_title :y %>
         grid: {
           color: <%= CssVariable['--grid-line-color'].to_json %>
         },
+        ticks: {
+          callback: function(value, index, ticks) {
+            return index === ticks.length - 1 ? null : value;
+          }
+        }
       }
     },
     plugins: {

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/pull_request_cycle_time_histogram.rb

@@ -19,8 +19,8 @@ class PullRequestCycleTimeHistogram < TimeBasedHistogram
     HTML
 
     init_configuration_block(block) do
-      grouping_rules do |pull_request, _rule|
-        rules.label = pull_request.repo
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
       end
     end
   end

data/lib/jirametrics/pull_request_cycle_time_scatterplot.rb

@@ -18,8 +18,8 @@ class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
     HTML
 
     init_configuration_block(block) do
-      grouping_rules do |pull_request, _rule|
-        rules.label = pull_request.repo
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
       end
     end
   end
@@ -48,8 +48,15 @@ class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
   end
 
   def y_value pull_request
-    divisor = { minutes: 60, hours: 3600, days: 86_400 }[@cycletime_unit]
-    ((pull_request.closed_at - pull_request.opened_at) / divisor).round
+    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
@@ -62,7 +69,8 @@ class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
 
   def title_value pull_request, rules: nil
     age_label = label_cycletime y_value(pull_request)
-    "#{pull_request.title} | #{rules.label} | Age:#{age_label}#{lines_changed_text(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

data/lib/jirametrics/stitcher.rb

@@ -60,6 +60,11 @@ class Stitcher < HtmlGenerator
         if matches[:seam] == 'start'
           content = +''
         else
+          if content.nil? || content.strip.empty?
+            file_system.warning "Seam found with no content in #{filename.inspect}: " \
+              "id=#{matches[:id].strip.inspect}, class=#{matches[:clazz].strip.inspect}, " \
+              "title=#{matches[:title].strip.inspect}"
+          end
           @all_stitches << Stitcher::StitchContent.new(
             file: filename, title: matches[:title], type: matches[:type], content: content
           )

data/lib/jirametrics.rb

@@ -52,6 +52,34 @@ class JiraMetrics < Thor
     Exporter.instance.info(key, name_filter: options[:name] || '*')
   end
 
+  option :config
+  option :name
+  desc 'mcp', 'Start in MCP (Model Context Protocol) server mode'
+  def mcp
+    load_config options[:config]
+    require 'jirametrics/mcp_server'
+
+    Exporter.instance.file_system.log_only = true
+
+    projects = {}
+    Exporter.instance.each_project_config(name_filter: options[:name] || '*') do |project|
+      project.evaluate_next_level
+      project.run load_only: true
+      projects[project.name || 'default'] = {
+        issues: project.issues,
+        today: project.time_range.end.to_date,
+        end_time: project.time_range.end
+      }
+    rescue StandardError => e
+      next if e.message.start_with? 'This is an aggregated project'
+      next if e.message.start_with? 'No data found'
+
+      raise
+    end
+
+    McpServer.new(projects: projects, timezone_offset: Exporter.instance.timezone_offset).run
+  end
+
   option :config
   desc 'stitch', 'Dump information about one issue'
   def stitch stitch_file = 'stitcher.erb'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: 2.26.1
+  version: '2.27'
 platform: ruby
 authors:
 - Mike Bowler
@@ -9,6 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: mutant-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: random-word
   requirement: !ruby/object:Gem::Requirement
@@ -131,6 +159,7 @@ files:
 - lib/jirametrics/issue_link.rb
 - lib/jirametrics/issue_printer.rb
 - lib/jirametrics/jira_gateway.rb
+- lib/jirametrics/mcp_server.rb
 - lib/jirametrics/project_config.rb
 - lib/jirametrics/pull_request.rb
 - lib/jirametrics/pull_request_cycle_time_histogram.rb