jirametrics 2.25 → 2.30

data/lib/jirametrics/sprint_burndown.rb

@@ -66,7 +66,7 @@ class SprintBurndown < ChartBase
     result = +''
     result << render_top_text(binding)
 
-    possible_colours = (1..5).collect { |i| CssVariable["--sprint-burndown-sprint-color-#{i}"] }
+    possible_colours = (1..ChartBase::OKABE_ITO_PALETTE.size).collect { |i| CssVariable["--sprint-burndown-sprint-color-#{i}"] }
     charts_to_generate = []
     charts_to_generate << [:data_set_by_story_points, 'Story Points'] if @use_story_points
     charts_to_generate << [:data_set_by_story_counts, 'Story Count'] if @use_story_counts

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

@@ -79,12 +79,21 @@ class ThroughputChart < ChartBase
     end
   end
 
+  def calculate_custom_periods
+    last_days = @issue_periods.values.compact.uniq.sort
+    last_days.each_with_index.map do |last_day, i|
+      first_day = i.zero? ? @date_range.begin : last_days[i - 1] + 1
+      first_day..last_day
+    end
+  end
+
   def weekly_throughput_dataset completed_issues:, label:, color:, dashed: false, label_hint: nil
+    periods = @issue_periods&.values&.any? ? calculate_custom_periods : calculate_time_periods
     result = {
       label: label,
       label_hint: label_hint,
       data: throughput_dataset(
-        periods: calculate_time_periods, completed_issues: completed_issues, label_hint: label_hint
+        periods: periods, completed_issues: completed_issues, label_hint: label_hint
       ),
       fill: false,
       showLine: true,
@@ -109,10 +118,17 @@ class ThroughputChart < ChartBase
   end
 
   def throughput_dataset periods:, completed_issues:, label_hint: nil
+    custom_mode = @issue_periods&.values&.any?
     periods.collect do |period|
       closed_issues = completed_issues.filter_map do |issue|
         stop_date = issue.started_stopped_dates.last
-        [stop_date, issue] if stop_date && period.include?(stop_date)
+        next unless stop_date
+
+        if custom_mode
+          [stop_date, issue] if @issue_periods[issue] == period.end
+        elsif period.include?(stop_date)
+          [stop_date, issue]
+        end
       end
 
       date_label = "on #{period.end}"

data/lib/jirametrics/time_based_scatterplot.rb

@@ -18,7 +18,7 @@ class TimeBasedScatterplot < ChartBase
     overall_percent_line = calculate_percent_line(items)
     @percentage_lines << [overall_percent_line, CssVariable['--cycletime-scatterplot-overall-trendline-color']]
 
-    return "<h1>#{@header_text}</h1>No data matched the selected criteria. Nothing to show." if data_sets.empty?
+    return "<h1 class='foldable'>#{@header_text}</h1><div>No data matched the selected criteria. Nothing to show.</div>" if data_sets.empty?
 
     wrap_and_render(binding, __FILE__)
   end
@@ -79,9 +79,14 @@ class TimeBasedScatterplot < ChartBase
     }
   end
 
+  def minimum_y_value
+    nil
+  end
+
   def data_for_item item, rules: nil
     y = y_value(item)
-    return nil if y < 1 # These will get called out on the quality report
+    min = minimum_y_value
+    return nil if min && y < min
 
     @highest_y_value = y if @highest_y_value < y
 
@@ -93,7 +98,9 @@ class TimeBasedScatterplot < ChartBase
   end
 
   def calculate_percent_line items
+    min = minimum_y_value
     times = items.collect { |item| y_value(item) }
+    times.reject! { |y| min && y < min }
     index = times.size * 85 / 100
     times.sort[index]
   end

data/lib/jirametrics/wip_by_column_chart.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'jirametrics/chart_base'
+
+class WipByColumnChart < ChartBase
+  attr_accessor :possible_statuses, :board_id
+
+  ColumnStats = Struct.new(:name, :min_wip_limit, :max_wip_limit, :wip_history, keyword_init: true)
+
+  def initialize block
+    super()
+    header_text 'WIP by column'
+    description_text <<-HTML
+      <p>
+        This chart shows how much time each board column has spent at different WIP (Work in Progress) levels.
+      </p>
+      <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 —
+        a wider bar means more time was spent there.
+      </p>
+      <p>
+        A column whose widest bar is at WIP&nbsp;1 was almost always working on one item at a time, often called
+        single-piece-flow. This team is likely collaborating very well and might have been
+        <a href="https://blog.mikebowler.ca/2021/06/19/pair-programming/">pairing</a> or
+        <a href="https://blog.mikebowler.ca/2023/04/22/ensemble-programming/">mobbing/ensembling</a>
+        and these teams tend to be very effective.
+      </p>
+      <p>
+        A column with wide bars at high WIP levels usually indicates a team that is highly siloed. Where each person
+        is working by themselves.
+      </p>
+      <p>
+        The dashed lines show the minimum and maximum WIP limits configured on the board.
+        If the widest bar sits well above the maximum limit, the limit may be set too low or not being respected.
+        If the widest bar sits below the minimum limit, consider whether that limit is still meaningful.
+      </p>
+      <p>
+        Hover over any bar to see the exact percentage.
+      </p>
+      <% if @all_boards[@board_id].team_managed_kanban? %>
+        <p>
+          If the data looks a bit off then that's probably because you're using a Team Managed project in "kanban mode".
+          For this specific case, we are unable to tell if an item is actually visible on the board and so we may
+          be reporting more items started than you actually see on the board. See
+          <a href="https://jirametrics.org/faq/#team-managed-kanban-backlog">the FAQ</a>.
+        </p>
+      <% end %>
+    HTML
+
+    instance_eval(&block)
+  end
+
+  def show_recommendations
+    @show_recommendations = true
+  end
+
+  def run
+    @header_text += " on board: #{current_board.name}"
+    stats = column_stats
+    @column_names = stats.collect(&:name)
+    @wip_data = stats.collect do |stat|
+      total = stat.wip_history.sum { |_wip, seconds| seconds }.to_f
+      next [] if total.zero?
+
+      stat.wip_history.collect { |wip, seconds| { 'wip' => wip, 'pct' => format_pct(seconds, total) } }
+    end
+    @max_wip = stats.flat_map { |s| s.wip_history.collect { |wip, _| wip } }.max || 0
+    @wip_limits = stats.collect { |s| { 'min' => s.min_wip_limit, 'max' => s.max_wip_limit } }
+    @recommendations = @show_recommendations ? compute_recommendations(stats) : Array.new(stats.size)
+
+    trim_zero_end_columns
+    @recommendation_texts = @show_recommendations ? build_recommendation_texts : []
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def column_stats
+    board = current_board
+    columns = board.visible_columns
+    status_to_column = build_status_to_column_map(columns)
+    relevant_issues = @issues.select { |issue| issue.board.id == @board_id }
+
+    current_column = initial_column_state(relevant_issues, status_to_column)
+    events = events_within_range(relevant_issues, status_to_column)
+    column_wip_seconds = compute_wip_seconds(columns, current_column, events)
+
+    columns.collect.with_index do |column, index|
+      ColumnStats.new(
+        name: column.name,
+        min_wip_limit: column.min,
+        max_wip_limit: column.max,
+        wip_history: column_wip_seconds[index].sort.to_a
+      )
+    end
+  end
+
+  private
+
+  def trim_zero_end_columns
+    all_zero = @wip_data.map { |col| col.none? { |e| e['wip'].positive? } }
+    first = all_zero.index(false)
+    return unless first
+
+    last = all_zero.rindex(false)
+    @column_names    = @column_names[first..last]
+    @wip_data        = @wip_data[first..last]
+    @wip_limits      = @wip_limits[first..last]
+    @recommendations = @recommendations[first..last]
+    @max_wip         = @wip_data.flat_map { |col| col.map { |e| e['wip'] } }.max || 0
+  end
+
+  def compute_recommendations stats
+    stats.collect do |stat|
+      next nil if stat.wip_history.empty?
+
+      total = stat.wip_history.sum { |_wip, seconds| seconds }.to_f
+      next nil if total.zero?
+
+      cumulative = 0
+      stat.wip_history.sort.find do |_wip, seconds|
+        cumulative += seconds
+        cumulative / total >= 0.85
+      end&.first
+    end
+  end
+
+  def build_recommendation_texts
+    @column_names.each_with_index.filter_map do |name, i|
+      rec = @recommendations[i]
+      next if rec.nil?
+
+      next "Almost nothing passes through column '#{name}'. Do we still need it?" if rec.zero?
+
+      max = @wip_limits[i]['max']
+      if max.nil?
+        "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
+        "Raise the WIP limit for '#{name}' from #{max} to #{rec}"
+      end
+    end
+  end
+
+  def format_pct seconds, total
+    raw = seconds / total * 100.0
+    (1..10).each do |decimals|
+      rounded = raw.round(decimals)
+      next if rounded.zero? && raw.positive?
+      next if rounded >= 100.0 && raw < 100.0
+
+      return rounded
+    end
+    raw
+  end
+
+  def build_status_to_column_map columns
+    columns.each_with_object({}).with_index do |(column, map), index|
+      column.status_ids.each { |id| map[id] = index }
+    end
+  end
+
+  def initial_column_state relevant_issues, status_to_column
+    relevant_issues.each_with_object({}) do |issue, hash|
+      started_time, stopped_time = issue.board.cycletime.started_stopped_times(issue)
+      in_wip = started_time &&
+               started_time <= time_range.begin &&
+               (stopped_time.nil? || stopped_time > time_range.begin)
+      unless in_wip
+        hash[issue] = nil
+        next
+      end
+
+      last_change = issue.status_changes.reverse.find { |c| c.time <= time_range.begin }
+      hash[issue] = last_change ? status_to_column[last_change.value_id] : nil
+    end
+  end
+
+  def events_within_range relevant_issues, status_to_column
+    events = []
+    relevant_issues.each do |issue|
+      started_time, stopped_time = issue.board.cycletime.started_stopped_times(issue)
+      next unless started_time
+
+      # Issue starts within the window: add an explicit event to enter WIP in its current column
+      if started_time > time_range.begin && started_time <= time_range.end
+        last_change = issue.status_changes.reverse.find { |c| c.time <= started_time }
+        events << [started_time, issue, last_change ? status_to_column[last_change.value_id] : nil]
+      end
+
+      # Status changes while the issue is actively in WIP and within the window
+      issue.status_changes.each do |change|
+        next unless change.time > time_range.begin
+        next if change.time > time_range.end
+        next unless change.time >= started_time
+        next if stopped_time && change.time >= stopped_time
+
+        events << [change.time, issue, status_to_column[change.value_id]]
+      end
+
+      # Issue stops within the window: add an explicit event to exit WIP
+      if stopped_time && stopped_time > time_range.begin && stopped_time <= time_range.end
+        events << [stopped_time, issue, nil]
+      end
+    end
+    events.sort_by!(&:first)
+  end
+
+  def compute_wip_seconds columns, current_column, events
+    wip_counts = Array.new(columns.size, 0)
+    current_column.each_value { |col| wip_counts[col] += 1 unless col.nil? }
+
+    column_wip_seconds = Array.new(columns.size) { Hash.new(0) }
+    prev_time = time_range.begin
+
+    events.each do |time, issue, new_col|
+      elapsed = (time - prev_time).to_i
+      if elapsed.positive?
+        wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed }
+        prev_time = time
+      end
+
+      old_col = current_column[issue]
+      wip_counts[old_col] -= 1 unless old_col.nil?
+      wip_counts[new_col] += 1 unless new_col.nil?
+      current_column[issue] = new_col
+    end
+
+    elapsed = (time_range.end - prev_time).to_i
+    wip_counts.each_with_index { |wip, idx| column_wip_seconds[idx][wip] += elapsed } if elapsed.positive?
+
+    column_wip_seconds
+  end
+end

data/lib/jirametrics.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'English'
 require 'thor'
 require 'require_all'
 
@@ -52,6 +53,47 @@ 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
+    # Redirect stdout to stderr for the entire startup phase so that any
+    # incidental output (from config files, gem loading, etc.) does not
+    # corrupt the JSON-RPC channel before the MCP transport takes over.
+    original_stdout = $stdout.dup
+    $stdout.reopen($stderr)
+
+    load_config options[:config]
+    require 'jirametrics/mcp_server'
+
+    Exporter.instance.file_system.log_only = true
+
+    projects = {}
+    aggregates = {}
+    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
+      if e.message.start_with? 'This is an aggregated project'
+        names = project.aggregate_project_names
+        aggregates[project.name] = names if names.any?
+        next
+      end
+      next if e.message.start_with? 'No data found'
+
+      raise
+    end
+
+    $stdout.reopen(original_stdout)
+    original_stdout.close
+    McpServer.new(projects: projects, aggregates: aggregates, timezone_offset: Exporter.instance.timezone_offset).run
+  end
+
   option :config
   desc 'stitch', 'Dump information about one issue'
   def stitch stitch_file = 'stitcher.erb'
@@ -59,6 +101,22 @@ class JiraMetrics < Thor
     Exporter.instance.stitch stitch_file
   end
 
+  def self.log_uncaught_exception exception, file_system: nil
+    return unless exception && !exception.is_a?(SystemExit)
+
+    begin
+      file_system ||= Exporter.instance.file_system
+      return if file_system.logfile == $stdout
+
+      file_system.logfile.puts "#{exception.class}: #{exception.message}"
+      exception.backtrace&.each { |line| file_system.logfile.puts "\t#{line}" }
+    rescue StandardError
+      # Exporter may not be initialized, or the logfile may already be closed
+    end
+  end
+
+  at_exit { JiraMetrics.log_uncaught_exception $ERROR_INFO }
+
   no_commands do
     def load_config config_file, file_system: FileSystem.new
       config_file = './config.rb' if config_file.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '2.25'
+  version: '2.30'
 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
@@ -55,10 +83,12 @@ description: Extract metrics from Jira and export to either a report or to CSV f
 email: mbowler@gargoylesoftware.com
 executables:
 - jirametrics
+- jirametrics-mcp
 extensions: []
 extra_rdoc_files: []
 files:
 - bin/jirametrics
+- bin/jirametrics-mcp
 - lib/jirametrics.rb
 - lib/jirametrics/aggregate_config.rb
 - lib/jirametrics/aging_work_bar_chart.rb
@@ -120,10 +150,12 @@ files:
 - lib/jirametrics/html/index.css
 - lib/jirametrics/html/index.erb
 - lib/jirametrics/html/index.js
+- lib/jirametrics/html/legacy_colors.css
 - lib/jirametrics/html/sprint_burndown.erb
 - lib/jirametrics/html/throughput_chart.erb
 - lib/jirametrics/html/time_based_histogram.erb
 - lib/jirametrics/html/time_based_scatterplot.erb
+- lib/jirametrics/html/wip_by_column_chart.erb
 - lib/jirametrics/html_generator.rb
 - lib/jirametrics/html_report_config.rb
 - lib/jirametrics/issue.rb
@@ -131,6 +163,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
@@ -154,6 +187,7 @@ files:
 - lib/jirametrics/trend_line_calculator.rb
 - lib/jirametrics/user.rb
 - lib/jirametrics/value_equality.rb
+- lib/jirametrics/wip_by_column_chart.rb
 homepage: https://jirametrics.org
 licenses:
 - Apache-2.0
@@ -176,7 +210,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Extract Jira metrics
 test_files: []