jirametrics 2.7 → 2.11

data/lib/jirametrics/status_collection.rb

@@ -4,64 +4,68 @@ 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
+
+    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
@@ -69,7 +73,37 @@ class StatusCollection
   def clear = @list.clear
   def delete(object) = @list.delete(object)
 
+  def to_s
+    "[#{@list.sort.join(', ')}]"
+  end
+
   def inspect
-    "StatusCollection(#{@list.collect(&:inspect).join(', ')})"
+    "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.started_stopped_times(issue).last&.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

@@ -7,6 +7,13 @@ class JiraMetrics < Thor
     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', "Export data into either reports or CSV's as per the configuration"
@@ -61,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'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '2.7'
+  version: '2.11'
 platform: ruby
 authors:
 - Mike Bowler
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-27 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
@@ -106,7 +104,6 @@ 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
@@ -132,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
@@ -155,8 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-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.discard_changes_before cutoff_time
-    end
-  end
-end

data/lib/jirametrics/html/data_quality_report.erb

@@ -1,138 +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 :incomplete_subtasks_when_issue_done
-  unless problems.empty? 
-%>
-  <p>
-    <span class="quality_note_bullet">⮕</span> <%= label_issues problems.size %> issues were marked as done while subtasks were still not done.
-    <%= 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
-%>