jirametrics 2.4 → 2.11

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

@@ -4,68 +4,106 @@ 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 StatusNotFoundError, "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
 
-  def find_by_name name
-    find { |status| status.name == name }
+    if identifier.is_a? Symbol
+      key = identifier.to_s
+    else
+      name, id = parse_name_id identifier
+    end
+
+    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

@@ -82,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,6 @@ 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'
@@ -69,6 +86,7 @@ class JiraMetrics < Thor
     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'
@@ -97,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.4'
+  version: '2.11'
 platform: ruby
 authors:
 - Mike Bowler
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-17 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,6 +69,7 @@ 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
@@ -84,7 +83,6 @@ files:
 - 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
@@ -95,6 +93,7 @@ files:
 - 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
@@ -105,9 +104,9 @@ 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
@@ -130,15 +129,14 @@ files:
 - 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
@@ -153,8 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.15
-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

data/lib/jirametrics/html/data_quality_report.erb

@@ -1,126 +0,0 @@
-<% 
-  problems = problems_for :discarded_changes
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> have had information discarded. This configuration is set
-    to "reset the clock" if an item is moved back to the backlog after it's been started. This hides important
-    information and makes the data less accurate. <b>Moving items back to the backlog is strongly discouraged.</b>
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :completed_but_not_started
-  unless problems.empty?
-    percentage_work_included = ((issues.size - problems.size).to_f / issues.size * 100).to_i
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were discarded from all charts using cycletime (scatterplot, histogram, etc) as we couldn't determine when they started. 
-    <% if percentage_work_included < 85 %>
-      Consider whether looking at only <%= percentage_work_included %>% of the total data points is enough to come to any reasonable conclusions. See <a href="https://en.wikipedia.org/wiki/Survivorship_bias">Survivorship Bias</a>.
-    <% end %>
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :status_changes_after_done
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> had a status change after being identified as done. We should question whether they were really done at that point or if we stopped the clock too early.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :backwards_through_status_categories
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> moved backwards across the board, <b>crossing status categories</b>. This will almost certainly have impacted timings as the end times are often taken at status category boundaries. You should assume that any timing measurements for this item are wrong.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :backwords_through_statuses
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> moved backwards across the board. Depending where we have set the start and end points, this may give us incorrect timing data. Note that these items did not cross a status category and may not have affected metrics.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :status_not_on_board
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were not visible on the board for some period of time. This may impact timings as the work was likely to have been forgotten if it wasn't visible.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :created_in_wrong_status
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were created in a status not designated as Backlog. This will impact the measurement of start times and will therefore impact whether it's shown as in progress or not.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :stopped_before_started
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> were stopped before they were started and this will play havoc with any cycletime or WIP calculations. The most common case for this is when an item gets closed and then moved back into an in-progress status.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :issue_not_started_but_subtasks_have
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> still showing 'not started' while sub-tasks underneath them have started. This is almost always a mistake; if we're working on subtasks, the top level
-    item should also have started.
-    <%= collapsible_issues_panel problems %>
-  </p>
-<% 
-  end
-%>
-
-<% 
-  problems = problems_for :issue_on_multiple_boards
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> For <%= label_issues problems.size %>, we have an issue that shows up on more than one board. This could result in more data points showing up on a chart then there really should be.
-    <%= collapsible_issues_panel problems, :hide_board_column %>
-  </p>
-<% 
-  end
-%>