jirametrics 2.0 → 2.11

data/lib/jirametrics/sprint_burndown.rb

@@ -18,11 +18,17 @@ class SprintBurndown < ChartBase
   attr_accessor :board_id
 
   def initialize
-    super()
+    super
 
     @summary_stats = {}
     header_text 'Sprint burndown'
-    description_text ''
+    description_text <<-TEXT
+      <div class="p">
+        Burndowns for all sprints in this time period. The different colours are only to
+        differentiate one sprint from another as they may overlap time periods.
+      </div>
+      #{describe_non_working_days}
+    TEXT
   end
 
   def options= arg
@@ -55,9 +61,9 @@ class SprintBurndown < ChartBase
     end
 
     result = +''
-    result << '<h1>Sprint Burndowns</h1>'
+    result << render_top_text(binding)
 
-    possible_colours = %w[blue orange green red brown]
+    possible_colours = (1..5).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
@@ -65,7 +71,7 @@ class SprintBurndown < ChartBase
       @summary_stats.clear
       data_sets = []
       sprints.each_with_index do |sprint, index|
-        color = possible_colours[index % 5]
+        color = possible_colours[index % possible_colours.size]
         label = sprint.name
         data = send(data_method, sprint: sprint, change_data_for_sprint: change_data_by_sprint[sprint])
         data_sets << {
@@ -102,6 +108,17 @@ class SprintBurndown < ChartBase
     result
   end
 
+  def sprints_in_time_range board
+    board.sprints.select do |sprint|
+      sprint_end_time = sprint.completed_time || sprint.end_time
+      sprint_start_time = sprint.start_time
+      next false if sprint_start_time.nil?
+
+      time_range.include?(sprint_start_time) || time_range.include?(sprint_end_time) ||
+        (sprint_start_time < time_range.begin && sprint_end_time > time_range.end)
+    end || []
+  end
+
   # select all the changes that are relevant for the sprint. If this issue never appears in this sprint then return [].
   def changes_for_one_issue issue:, sprint:
     story_points = 0.0
@@ -109,7 +126,7 @@ class SprintBurndown < ChartBase
     currently_in_sprint = false
     change_data = []
 
-    issue_completed_time = issue.board.cycletime.stopped_time(issue)
+    issue_completed_time = issue.board.cycletime.started_stopped_times(issue).last
     completed_has_been_tracked = false
 
     issue.changes.each do |change|
@@ -155,7 +172,7 @@ class SprintBurndown < ChartBase
     change_item.raw['to'].split(/\s*,\s*/).any? { |id| id.to_i == sprint.id }
   end
 
-  def data_set_by_story_points sprint:, change_data_for_sprint:
+  def data_set_by_story_points sprint:, change_data_for_sprint: # rubocop:disable Metrics/CyclomaticComplexity
     summary_stats = SprintSummaryStats.new
     summary_stats.completed = 0.0
 

data/lib/jirametrics/status.rb

@@ -3,30 +3,65 @@
 require 'jirametrics/value_equality'
 
 class Status
-  include ValueEquality
-  attr_reader :id, :category_name, :category_id, :project_id
+  attr_reader :id, :project_id, :category
   attr_accessor :name
 
-  def initialize name: nil, id: nil, category_name: nil, category_id: nil, project_id: nil, raw: nil
-    @name = name
-    @id = id
-    @category_name = category_name
-    @category_id = category_id
-    @project_id = project_id
+  class Category
+    attr_reader :id, :name, :key
+
+    def initialize id:, name:, key:
+      @id = id
+      @name = name
+      @key = key
+    end
 
-    return unless raw
+    def to_s
+      "#{name.inspect}:#{id.inspect}"
+    end
 
-    @raw = raw
-    @name = raw['name']
-    @id = raw['id'].to_i
+    def <=> other
+      id <=> other.id
+    end
+
+    def == other
+      id == other.id
+    end
+
+    def eql?(other) = id.eql?(other.id)
+    def hash = id.hash
+
+    def new? = (@key == 'new')
+    def indeterminate? = (@key == 'indeterminate')
+    def done? = (@key == 'done')
+  end
+
+  def self.from_raw raw
+    raise "raw cannot be nil" if raw.nil?
 
     category_config = raw['statusCategory']
-    @category_name = category_config['name']
-    @category_id = category_config['id'].to_i
+    raise "statusCategory can't be nil in #{category_config.inspect}" if category_config.nil?
+
+    Status.new(
+      name: raw['name'],
+      id: raw['id'].to_i,
+      category_name: category_config['name'],
+      category_id: category_config['id'].to_i,
+      category_key: category_config['key'],
+      project_id: raw['scope']&.[]('project')&.[]('id'),
+      artificial: false
+    )
+  end
+
+  def initialize name:, id:, category_name:, category_id:, category_key:, project_id: nil, artificial: true
+    # These checks are needed because nils used to be possible and now they aren't.
+    raise 'id cannot be nil' if id.nil?
+    raise 'category_id cannot be nil' if category_id.nil?
 
-    # If this is a NextGen project then this status may be project specific. When this field is
-    # nil then the status is global.
-    @project_id = raw['scope']&.[]('project')&.[]('id')
+    @name = name
+    @id = id
+    @category = Category.new id: category_id, name: category_name, key: category_key
+    @project_id = project_id
+    @artificial = artificial
   end
 
   def project_scoped?
@@ -38,8 +73,38 @@ class Status
   end
 
   def to_s
-    "Status(name=#{@name.inspect}, id=#{@id.inspect}," \
-      " category_name=#{@category_name.inspect}, category_id=#{@category_id.inspect}, project_id=#{@project_id})"
+    "#{name.inspect}:#{id.inspect}"
+  end
+
+  def artificial?
+    @artificial
+  end
+
+  def == other
+    return false unless other.is_a? Status
+
+    @id == other.id && @name == other.name && @category.id == other.category.id && @category.name == other.category.name
+  end
+
+  def eql?(other)
+    self == other
+  end
+
+  def <=> other
+    result = @name.casecmp(other.name)
+    result = @id <=> other.id if result.zero?
+    result
+  end
+
+  def inspect
+    result = []
+    result << "Status(name: #{@name.inspect}"
+    result << "id: #{@id.inspect}"
+    result << "project_id: #{@project_id}" if @project_id
+    category = self.category
+    result << "category: {name:#{category.name.inspect}, id: #{category.id.inspect}, key: #{category.key.inspect}}"
+    result << 'artificial' if artificial?
+    result.join(', ') << ')'
   end
 
   def value_equality_ignored_variables

data/lib/jirametrics/status_collection.rb

@@ -1,68 +1,109 @@
 # frozen_string_literal: true
 
+class StatusNotFoundError < StandardError
+end
+
 class StatusCollection
+  attr_reader :historical_status_mappings
+
   def initialize
     @list = []
+    @historical_status_mappings = {} # 'name:id' => category
   end
 
-  def filter_status_names category_name:, including: nil, excluding: nil
-    including = expand_statuses including
-    excluding = expand_statuses excluding
+  # Return the status matching this id or nil if it can't be found.
+  def find_by_id id
+    @list.find { |status| status.id == id }
+  end
 
-    @list.filter_map do |status|
-      keep = status.category_name == category_name ||
-        including.any? { |s| s.name == status.name }
-      keep = false if excluding.any? { |s| s.name == status.name }
+  def find_all_by_name identifier
+    name, id = parse_name_id identifier
 
-      status.name if keep
-    end
-  end
+    if id
+      status = find_by_id id
+      return [] if status.nil?
 
-  def expand_statuses names_or_ids
-    result = []
-    return result if names_or_ids.nil?
-
-    names_or_ids = [names_or_ids] unless names_or_ids.is_a? Array
-
-    names_or_ids.each do |name_or_id|
-      status = @list.find { |s| s.name == name_or_id || s.id == name_or_id }
-      if status.nil?
-        if block_given?
-          yield name_or_id
-          next
-        else
-          all_status_names = @list.collect { |s| "#{s.name.inspect}:#{s.id.inspect}" }.uniq.sort.join(', ')
-          raise "Status not found: #{name_or_id}. Possible statuses are: #{all_status_names}"
-        end
+      if name && status.name != name
+        raise "Specified status ID of #{id} does not match specified name #{name.inspect}. " \
+          "You might have meant one of these: #{self}."
       end
-
-      result << status
+      [status]
+    else
+      @list.select { |status| status.name == name }
     end
-    result
   end
 
-  def todo including: nil, excluding: nil
-    filter_status_names category_name: 'To Do', including: including, excluding: excluding
+  def find_all_categories
+    @list
+      .collect(&:category)
+      .uniq
+      .sort_by(&:id)
   end
 
-  def in_progress including: nil, excluding: nil
-    filter_status_names category_name: 'In Progress', including: including, excluding: excluding
+  def parse_name_id name
+    # Names could arrive in one of the following formats: "Done:3", "3", "Done"
+    if name =~ /^(.*):(\d+)$/
+      [$1, $2.to_i]
+    elsif name.match?(/^\d+$/)
+      [nil, name.to_i]
+    else
+      [name, nil]
+    end
   end
 
-  def done including: nil, excluding: nil
-    filter_status_names category_name: 'Done', including: including, excluding: excluding
-  end
+  def find_all_categories_by_name identifier
+    key = nil
+    id = nil
+
+    if identifier.is_a? Symbol
+      key = identifier.to_s
+    else
+      name, id = parse_name_id identifier
+    end
 
-  def find_by_name name
-    find { |status| status.name == name }
+    find_all_categories.select { |c| c.id == id || c.name == name || c.key == key }
   end
 
-  def find(&block)= @list.find(&block)
   def collect(&block) = @list.collect(&block)
+  def find(&block) = @list.find(&block)
   def each(&block) = @list.each(&block)
   def select(&block) = @list.select(&block)
   def <<(arg) = @list << arg
   def empty? = @list.empty?
   def clear = @list.clear
   def delete(object) = @list.delete(object)
+
+  def to_s
+    "[#{@list.sort.join(', ')}]"
+  end
+
+  def inspect
+    "StatusCollection#{self}"
+  end
+
+  def fabricate_status_for id:, name:
+    category = @historical_status_mappings["#{name.inspect}:#{id.inspect}"]
+    category = in_progress_category if category.nil?
+
+    status = Status.new(
+      name: name,
+      id: id,
+      category_name: category.name,
+      category_id: category.id,
+      category_key: category.key,
+      artificial: true
+    )
+    @list << status
+    status
+  end
+
+  private
+
+  # 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? }
+    raise "Can't find even one in-progress status in #{self}" unless first_in_progress_status
+
+    first_in_progress_status.category
+  end
 end

data/lib/jirametrics/throughput_chart.rb

@@ -5,11 +5,16 @@ class ThroughputChart < ChartBase
 
   attr_accessor :possible_statuses
 
-  def initialize block = nil
+  def initialize block
     super()
 
     header_text 'Throughput Chart'
-    description_text 'This chart shows how many items we completed per unit of time'
+    description_text <<-TEXT
+      <div class="p">
+        This chart shows how many items we completed per week
+      </div>
+      #{describe_non_working_days}
+    TEXT
 
     init_configuration_block(block) do
       grouping_rules do |issue, rule|
@@ -25,7 +30,10 @@ class ThroughputChart < ChartBase
     data_sets = []
     if rules_to_issues.size > 1
       data_sets << weekly_throughput_dataset(
-        completed_issues: completed_issues, label: 'Totals', color: 'gray', dashed: true
+        completed_issues: completed_issues,
+        label: 'Totals',
+        color: CssVariable['--throughput_chart_total_line_color'],
+        dashed: true
       )
     end
 
@@ -74,7 +82,7 @@ class ThroughputChart < ChartBase
   def throughput_dataset periods:, completed_issues:
     periods.collect do |period|
       closed_issues = completed_issues.filter_map do |issue|
-        stop_date = issue.board.cycletime.stopped_time(issue)&.to_date
+        stop_date = issue.board.cycletime.started_stopped_dates(issue).last
         [stop_date, issue] if stop_date && period.include?(stop_date)
       end
 

data/lib/jirametrics/value_equality.rb

@@ -9,9 +9,9 @@ module ValueEquality
       names = object.instance_variables
       if object.respond_to? :value_equality_ignored_variables
         ignored_variables = object.value_equality_ignored_variables
-        names.reject! { |n| ignored_variables.include? n }
+        names.reject! { |n| ignored_variables.include? n.to_sym }
       end
-      names.map { |variable| instance_variable_get variable }
+      names.map { |variable| object.instance_variable_get variable }
     end
 
     code.call(self) == code.call(other)

data/lib/jirametrics.rb

@@ -3,9 +3,20 @@
 require 'thor'
 
 class JiraMetrics < Thor
+  def self.exit_on_failure?
+    true
+  end
+
+  map %w[--version -v] => :__print_version
+
+  desc '--version, -v', 'print the version'
+  def __print_version
+    puts Gem.loaded_specs['jirametrics'].version
+  end
+
   option :config
   option :name
-  desc 'export only', "Export data into either reports or CSV's as per the configuration"
+  desc 'export', "Export data into either reports or CSV's as per the configuration"
   def export
     load_config options[:config]
     Exporter.instance.export(name_filter: options[:name] || '*')
@@ -13,7 +24,7 @@ class JiraMetrics < Thor
 
   option :config
   option :name
-  desc 'download only', 'Download data from Jira'
+  desc 'download', 'Download data from Jira'
   def download
     load_config options[:config]
     Exporter.instance.download(name_filter: options[:name] || '*')
@@ -21,7 +32,7 @@ class JiraMetrics < Thor
 
   option :config
   option :name
-  desc 'download and export', 'Same as running download, followed by export'
+  desc 'go', 'Same as running download, followed by export'
   def go
     load_config options[:config]
     Exporter.instance.download(name_filter: options[:name] || '*')
@@ -30,6 +41,13 @@ class JiraMetrics < Thor
     Exporter.instance.export(name_filter: options[:name] || '*')
   end
 
+  option :config
+  desc 'info', 'Dump information about one issue'
+  def info keys
+    load_config options[:config]
+    Exporter.instance.info(keys, name_filter: options[:name] || '*')
+  end
+
   private
 
   def load_config config_file
@@ -50,7 +68,7 @@ class JiraMetrics < Thor
     require 'jirametrics/grouping_rules'
     require 'jirametrics/daily_wip_chart'
     require 'jirametrics/groupable_issue_chart'
-    require 'jirametrics/discard_changes_before'
+    require 'jirametrics/css_variable'
 
     require 'jirametrics/aggregate_config'
     require 'jirametrics/expedited_chart'
@@ -60,13 +78,15 @@ class JiraMetrics < Thor
     require 'jirametrics/trend_line_calculator'
     require 'jirametrics/status'
     require 'jirametrics/issue_link'
-    require 'jirametrics/story_point_accuracy_chart'
+    require 'jirametrics/estimate_accuracy_chart'
     require 'jirametrics/status_collection'
     require 'jirametrics/sprint'
     require 'jirametrics/issue'
     require 'jirametrics/daily_wip_by_age_chart'
+    require 'jirametrics/daily_wip_by_parent_chart'
     require 'jirametrics/aging_work_in_progress_chart'
     require 'jirametrics/cycletime_scatterplot'
+    require 'jirametrics/flow_efficiency_scatterplot'
     require 'jirametrics/sprint_issue_change_data'
     require 'jirametrics/cycletime_histogram'
     require 'jirametrics/daily_wip_by_blocked_stalled_chart'
@@ -95,6 +115,4 @@ class JiraMetrics < Thor
     require 'jirametrics/board'
     load config_file
   end
-
-  # Dir.foreach('lib/jirametrics') {|file| puts "require 'jirametrics/#{$1}'" if file =~ /^(.+)\.rb$/}
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '2.0'
+  version: '2.11'
 platform: ruby
 authors:
 - Mike Bowler
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-22 00:00:00.000000000 Z
+date: 2025-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: random-word
@@ -52,8 +51,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.2
-description: Tool to extract metrics from Jira and export to either a report or to
-  CSV files
+description: Extract metrics from Jira and export to either a report or to CSV files
 email: mbowler@gargoylesoftware.com
 executables:
 - jirametrics
@@ -71,29 +69,31 @@ files:
 - lib/jirametrics/board.rb
 - lib/jirametrics/board_column.rb
 - lib/jirametrics/board_config.rb
+- lib/jirametrics/board_movement_calculator.rb
 - lib/jirametrics/change_item.rb
 - lib/jirametrics/chart_base.rb
 - lib/jirametrics/columns_config.rb
+- lib/jirametrics/css_variable.rb
 - lib/jirametrics/cycletime_config.rb
 - lib/jirametrics/cycletime_histogram.rb
 - lib/jirametrics/cycletime_scatterplot.rb
 - lib/jirametrics/daily_wip_by_age_chart.rb
 - lib/jirametrics/daily_wip_by_blocked_stalled_chart.rb
+- lib/jirametrics/daily_wip_by_parent_chart.rb
 - lib/jirametrics/daily_wip_chart.rb
 - lib/jirametrics/data_quality_report.rb
 - lib/jirametrics/dependency_chart.rb
-- lib/jirametrics/discard_changes_before.rb
 - lib/jirametrics/download_config.rb
 - lib/jirametrics/downloader.rb
+- lib/jirametrics/estimate_accuracy_chart.rb
 - lib/jirametrics/examples/aggregated_project.rb
 - lib/jirametrics/examples/standard_project.rb
 - lib/jirametrics/expedited_chart.rb
-- lib/jirametrics/experimental/generator.rb
-- lib/jirametrics/experimental/info.rb
 - lib/jirametrics/exporter.rb
 - lib/jirametrics/file_config.rb
 - lib/jirametrics/file_system.rb
 - lib/jirametrics/fix_version.rb
+- lib/jirametrics/flow_efficiency_scatterplot.rb
 - lib/jirametrics/groupable_issue_chart.rb
 - lib/jirametrics/grouping_rules.rb
 - lib/jirametrics/hierarchy_table.rb
@@ -104,12 +104,13 @@ files:
 - lib/jirametrics/html/cycletime_histogram.erb
 - lib/jirametrics/html/cycletime_scatterplot.erb
 - lib/jirametrics/html/daily_wip_chart.erb
-- lib/jirametrics/html/data_quality_report.erb
+- lib/jirametrics/html/estimate_accuracy_chart.erb
 - lib/jirametrics/html/expedited_chart.erb
+- lib/jirametrics/html/flow_efficiency_scatterplot.erb
 - lib/jirametrics/html/hierarchy_table.erb
+- lib/jirametrics/html/index.css
 - lib/jirametrics/html/index.erb
 - lib/jirametrics/html/sprint_burndown.erb
-- lib/jirametrics/html/story_point_accuracy_chart.erb
 - lib/jirametrics/html/throughput_chart.erb
 - lib/jirametrics/html_report_config.rb
 - lib/jirametrics/issue.rb
@@ -118,25 +119,24 @@ files:
 - lib/jirametrics/project_config.rb
 - lib/jirametrics/rules.rb
 - lib/jirametrics/self_or_issue_dispatcher.rb
+- lib/jirametrics/settings.json
 - lib/jirametrics/sprint.rb
 - lib/jirametrics/sprint_burndown.rb
 - lib/jirametrics/sprint_issue_change_data.rb
 - lib/jirametrics/status.rb
 - lib/jirametrics/status_collection.rb
-- lib/jirametrics/story_point_accuracy_chart.rb
 - lib/jirametrics/throughput_chart.rb
 - lib/jirametrics/tree_organizer.rb
 - lib/jirametrics/trend_line_calculator.rb
 - lib/jirametrics/value_equality.rb
-homepage: https://github.com/mikebowler/jirametrics
+homepage: https://jirametrics.org
 licenses:
 - Apache-2.0
 metadata:
   rubygems_mfa_required: 'true'
   bug_tracker_uri: https://github.com/mikebowler/jirametrics/issues
-  changelog_uri: https://github.com/mikebowler/jirametrics/wiki/Changes
-  documentation_uri: https://github.com/mikebowler/jirametrics/wiki
-post_install_message:
+  changelog_uri: https://jirametrics.org/changes
+  documentation_uri: https://jirametrics.org
 rdoc_options: []
 require_paths:
 - lib
@@ -151,8 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Extract Jira metrics
 test_files: []

data/lib/jirametrics/discard_changes_before.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module DiscardChangesBefore
-  def discard_changes_before status_becomes: nil, &block
-    if status_becomes
-      status_becomes = [status_becomes] unless status_becomes.is_a? Array
-
-      block = lambda do |issue|
-        trigger_statuses = status_becomes.collect do |status_name|
-          if status_name == :backlog
-            issue.board.backlog_statuses.collect(&:name)
-          else
-            status_name
-          end
-        end.flatten
-
-        time = nil
-        issue.changes.each do |change|
-          time = change.time if change.status? && trigger_statuses.include?(change.value) && change.artificial? == false
-        end
-        time
-      end
-    end
-
-    issues_cutoff_times = []
-    issues.each do |issue|
-      cutoff_time = block.call(issue)
-      issues_cutoff_times << [issue, cutoff_time] if cutoff_time
-    end
-
-    discard_changes_before_hook issues_cutoff_times
-
-    issues_cutoff_times.each do |issue, cutoff_time|
-      issue.changes.reject! { |change| change.status? && change.time <= cutoff_time && change.artificial? == false }
-    end
-  end
-end