jirametrics 1.0.0

data/lib/jirametrics/data_quality_report.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+class DataQualityReport < ChartBase
+  attr_reader :original_issue_times # For testing purposes only
+  attr_accessor :board_id
+
+  class Entry
+    attr_reader :started, :stopped, :issue, :problems
+
+    def initialize started:, stopped:, issue:
+      @started = started
+      @stopped = stopped
+      @issue = issue
+      @problems = []
+    end
+
+    def report problem_key: nil, detail: nil
+      @problems << [problem_key, detail]
+    end
+  end
+
+  def initialize original_issue_times
+    super()
+
+    @original_issue_times = original_issue_times
+
+    header_text 'Data Quality Report'
+    description_text <<-HTML
+      <p>
+        We have a tendency to assume that anything we see in a chart is 100% accurate, although that's
+        not always true. To understand the accuracy of the chart, we have to understand how accurate the
+        initial data was and also how much of the original data set was used in the chart. This section
+        will hopefully give you enough information to make that decision.
+      </p>
+    HTML
+  end
+
+  def run
+    initialize_entries
+
+    @entries.each do |entry|
+      board = entry.issue.board
+      backlog_statuses = board.backlog_statuses
+
+      scan_for_completed_issues_without_a_start_time entry: entry
+      scan_for_status_change_after_done entry: entry
+      scan_for_backwards_movement entry: entry, backlog_statuses: backlog_statuses
+      scan_for_issues_not_created_in_a_backlog_status entry: entry, backlog_statuses: backlog_statuses
+      scan_for_stopped_before_started entry: entry
+      scan_for_issues_not_started_with_subtasks_that_have entry: entry
+      scan_for_discarded_data entry: entry
+    end
+
+    scan_for_issues_on_multiple_boards entries: @entries
+
+    entries_with_problems = entries_with_problems()
+    return '' if entries_with_problems.empty?
+
+    wrap_and_render(binding, __FILE__)
+  end
+
+  def problems_for key
+    result = []
+    @entries.each do |entry|
+      entry.problems.each do |problem_key, detail|
+        result << [entry.issue, detail, key] if problem_key == key
+      end
+    end
+    result
+  end
+
+  # Return a format that's easier to assert against
+  def testable_entries
+    @entries.collect { |entry| [entry.started.to_s, entry.stopped.to_s, entry.issue] }
+  end
+
+  def entries_with_problems
+    @entries.reject { |entry| entry.problems.empty? }
+  end
+
+  def category_name_for status_name:, board:
+    board.possible_statuses.find { |status| status.name == status_name }&.category_name
+  end
+
+  def initialize_entries
+    @entries = @issues.collect do |issue|
+      cycletime = issue.board.cycletime
+      started = cycletime.started_time(issue)
+      stopped = cycletime.stopped_time(issue)
+      next if stopped && stopped < time_range.begin
+      next if started && started > time_range.end
+
+      Entry.new started: started, stopped: stopped, issue: issue
+    end.compact
+
+    @entries.sort! do |a, b|
+      a.issue.key =~ /.+-(\d+)$/
+      a_id = $1.to_i
+
+      b.issue.key =~ /.+-(\d+)$/
+      b_id = $1.to_i
+
+      a_id <=> b_id
+    end
+  end
+
+  def scan_for_completed_issues_without_a_start_time entry:
+    return unless entry.stopped && entry.started.nil?
+
+    status_names = entry.issue.changes.collect do |change|
+      next unless change.status?
+
+      format_status change.value, board: entry.issue.board
+    end.compact
+
+    entry.report(
+      problem_key: :completed_but_not_started,
+      detail: "Status changes: #{status_names.join ' → '}"
+    )
+  end
+
+  def scan_for_status_change_after_done entry:
+    return unless entry.stopped
+
+    changes_after_done = entry.issue.changes.select do |change|
+      change.status? && change.time >= entry.stopped
+    end
+    done_status = changes_after_done.shift.value
+
+    return if changes_after_done.empty?
+
+    board = entry.issue.board
+    problem = "Completed on #{entry.stopped.to_date} with status #{format_status done_status, board: board}."
+    changes_after_done.each do |change|
+      problem << " Changed to #{format_status change.value, board: board} on #{change.time.to_date}."
+    end
+    entry.report(
+      problem_key: :status_changes_after_done,
+      detail: problem
+    )
+  end
+
+  def scan_for_backwards_movement entry:, backlog_statuses:
+    issue = entry.issue
+
+    # Moving backwards through statuses is bad. Moving backwards through status categories is almost always worse.
+    last_index = -1
+    issue.changes.each do |change|
+      next unless change.status?
+
+      board = entry.issue.board
+      index = entry.issue.board.visible_columns.find_index { |column| column.status_ids.include? change.value_id }
+      if index.nil?
+        # If it's a backlog status then ignore it. Not supposed to be visible.
+        next if entry.issue.board.backlog_statuses.include? change.value_id
+
+        detail = "Status #{format_status change.value, board: board} is not on the board"
+        if issue.board.possible_statuses.expand_statuses(change.value).empty?
+          detail = "Status #{format_status change.value, board: board} cannot be found at all. Was it deleted?"
+        end
+
+        # If it's been moved back to backlog then it's on a different report. Ignore it here.
+        detail = nil if backlog_statuses.any? { |s| s.name == change.value }
+
+        entry.report(problem_key: :status_not_on_board, detail: detail) unless detail.nil?
+      elsif change.old_value.nil?
+        # Do nothing
+      elsif index < last_index
+        new_category = category_name_for(status_name: change.value, board: board)
+        old_category = category_name_for(status_name: change.old_value, board: board)
+
+        if new_category == old_category
+          entry.report(
+            problem_key: :backwords_through_statuses,
+            detail: "Moved from #{format_status change.old_value, board: board}" \
+              " to #{format_status change.value, board: board}" \
+              " on #{change.time.to_date}"
+          )
+        else
+          entry.report(
+            problem_key: :backwards_through_status_categories,
+            detail: "Moved from #{format_status change.old_value, board: board}" \
+              " to #{format_status change.value, board: board}" \
+              " on #{change.time.to_date}, " \
+              " crossing from category #{format_status old_category, board: board, is_category: true}" \
+              " to #{format_status new_category, board: board, is_category: true}."
+          )
+        end
+      end
+      last_index = index || -1
+    end
+  end
+
+  def scan_for_issues_not_created_in_a_backlog_status entry:, backlog_statuses:
+    return if backlog_statuses.empty?
+
+    creation_change = entry.issue.changes.find { |issue| issue.status? }
+
+    return if backlog_statuses.any? { |status| status.id == creation_change.value_id }
+
+    status_string = backlog_statuses.collect { |s| format_status s.name, board: entry.issue.board }.join(', ')
+    entry.report(
+      problem_key: :created_in_wrong_status,
+      detail: "Created in #{format_status creation_change.value, board: entry.issue.board}, " \
+        "which is not one of the backlog statuses for this board: #{status_string}"
+    )
+  end
+
+  def scan_for_stopped_before_started entry:
+    return unless entry.stopped && entry.started && entry.stopped < entry.started
+
+    entry.report(
+      problem_key: :stopped_before_started,
+      detail: "The stopped time '#{entry.stopped}' is before the started time '#{entry.started}'"
+    )
+  end
+
+  def scan_for_issues_not_started_with_subtasks_that_have entry:
+    return if entry.started
+
+    started_subtasks = []
+    entry.issue.subtasks.each do |subtask|
+      started_subtasks << subtask if subtask.board.cycletime.started_time(subtask)
+    end
+
+    return if started_subtasks.empty?
+
+    subtask_labels = started_subtasks.collect do |subtask|
+      "Started subtask: #{link_to_issue(subtask)} (#{format_status subtask.status.name, board: entry.issue.board}) " \
+        "#{subtask.summary[..50].inspect}"
+    end
+    entry.report(
+      problem_key: :issue_not_started_but_subtasks_have,
+      detail: subtask_labels.join('<br />')
+    )
+  end
+
+  def label_issues number
+    return '1 item' if number == 1
+
+    "#{number} items"
+  end
+
+  def scan_for_discarded_data entry:
+    hash = @original_issue_times[entry.issue]
+    return if hash.nil?
+
+    old_start_time = hash[:started_time]
+    cutoff_time = hash[:cutoff_time]
+
+    old_start_date = old_start_time.to_date
+    cutoff_date = cutoff_time.to_date
+
+    days_ignored = (cutoff_date - old_start_date).to_i + 1
+    message = "Started: #{old_start_date}, Discarded: #{cutoff_date}, Ignored: #{label_days days_ignored}"
+
+    # If days_ignored is zero then we don't really care as it won't affect any of the calculations.
+    return if days_ignored == 1
+
+    entry.report(
+      problem_key: :discarded_changes,
+      detail: message
+    )
+  end
+
+  def scan_for_issues_on_multiple_boards entries:
+    grouped_entries = entries.group_by { |entry| entry.issue.key }
+    grouped_entries.each_value do |entry_list|
+      next if entry_list.size == 1
+
+      board_names = entry_list.collect { |entry| entry.issue.board.name.inspect }
+      entry_list.first.report(
+        problem_key: :issue_on_multiple_boards,
+        detail: "Found on boards: #{board_names.join(', ')}"
+      )
+    end
+  end
+end

data/lib/jirametrics/dependency_chart.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'jirametrics/chart_base'
+require 'open3'
+require 'jirametrics/rules'
+
+class DependencyChart < ChartBase
+  class LinkRules < Rules
+    attr_accessor :line_color, :label
+
+    def merge_bidirectional keep: 'inward'
+      raise "Keep must be either inward or outward: #{keep}" unless %i[inward outward].include? keep.to_sym
+
+      @merge_bidirectional = keep.to_sym
+    end
+
+    def get_merge_bidirectional # rubocop:disable Naming/AccessorMethodName
+      @merge_bidirectional
+    end
+
+    def use_bidirectional_arrows
+      @use_bidirectional_arrows = true
+    end
+
+    def bidirectional_arrows?
+      @use_bidirectional_arrows
+    end
+  end
+
+  class IssueRules < Rules
+    attr_accessor :color, :label
+  end
+
+  def initialize rules_block
+    super()
+
+    header_text 'Dependencies'
+    description_text <<-HTML
+      <p>
+        These are all the "linked issues" as defined in Jira
+      </p>
+    HTML
+
+    @rules_block = rules_block
+    @link_rules_block = ->(link_name, link_rules) {}
+
+    issue_rules do |issue, rules|
+      key = issue.key
+      key = "<S>#{key} </S> " if issue.status.category_name == 'Done'
+      rules.label = "<#{key} [#{issue.type}]<BR/>#{word_wrap issue.summary}>"
+    end
+  end
+
+  def run
+    instance_eval(&@rules_block) if @rules_block
+
+    dot_graph = build_dot_graph
+    return "<h1>#{@header_text}</h1>No data matched the selected criteria. Nothing to show." if dot_graph.nil?
+
+    svg = execute_graphviz(dot_graph.join("\n"))
+    "<h1>#{@header_text}</h1><div>#{@description_text}</div>#{shrink_svg svg}"
+  end
+
+  def link_rules &block
+    @link_rules_block = block
+  end
+
+  def issue_rules &block
+    @issue_rules_block = block
+  end
+
+  def find_links
+    result = []
+    issues.each do |issue|
+      result += issue.issue_links
+    end
+    result
+  end
+
+  def make_dot_link issue_link:, link_rules:
+    result = String.new
+    result << issue_link.origin.key.inspect
+    result << ' -> '
+    result << issue_link.other_issue.key.inspect
+    result << '['
+    result << 'label=' << (link_rules.label || issue_link.label).inspect
+    result << ',color=' << (link_rules.line_color || 'black').inspect
+    result << ',dir=both' if link_rules.bidirectional_arrows?
+    result << '];'
+    result
+  end
+
+  def make_dot_issue issue:, issue_rules:
+    result = String.new
+    result << issue.key.inspect
+    result << '['
+    label = issue_rules.label || "#{issue.key}|#{issue.type}"
+    label = label.inspect unless label =~ /^<.+>$/
+    result << "label=#{label}"
+    result << ',shape=Mrecord'
+    tooltip = "#{issue.key}: #{issue.summary}"
+    result << ",tooltip=#{tooltip[0..80].inspect}"
+    unless issue_rules.color == :none
+      result << %(,style=filled,fillcolor="#{issue_rules.color || color_for(type: issue.type, shade: :light)}")
+    end
+    result << ']'
+    result
+  end
+
+  def build_dot_graph
+    issue_links = find_links
+
+    visible_issues = {}
+    link_graph = []
+    links_to_ignore = []
+
+    issue_links.each do |link|
+      next if links_to_ignore.include? link
+
+      link_rules = LinkRules.new
+      @link_rules_block.call link, link_rules
+
+      next if link_rules.ignored?
+
+      if link_rules.get_merge_bidirectional
+        opposite = issue_links.find do |l|
+          l.name == link.name && l.origin.key == link.other_issue.key && l.other_issue.key == link.origin.key
+        end
+        if opposite
+          # rubocop:disable Style/GuardClause
+          if link_rules.get_merge_bidirectional.to_sym == link.direction
+            # We keep this one and discard the opposite
+            links_to_ignore << opposite
+          else
+            # We keep the opposite and discard this one
+            next
+          end
+          # rubocop:enable Style/GuardClause
+        end
+      end
+
+      link_graph << make_dot_link(issue_link: link, link_rules: link_rules)
+
+      visible_issues[link.origin.key] = link.origin
+      visible_issues[link.other_issue.key] = link.other_issue
+    end
+
+    dot_graph = []
+    dot_graph << 'digraph mygraph {'
+    dot_graph << 'rankdir=LR'
+
+    # Sort the keys so they are proccessed in a deterministic order.
+    visible_issues.values.sort_by(&:key_as_i).each do |issue|
+      rules = IssueRules.new
+      @issue_rules_block.call(issue, rules)
+      dot_graph << make_dot_issue(issue: issue, issue_rules: rules)
+    end
+
+    dot_graph += link_graph
+    dot_graph << '}'
+
+    return nil if visible_issues.empty?
+    dot_graph
+  end
+
+  def execute_graphviz dot_graph
+    Open3.popen3('dot -Tsvg') do |stdin, stdout, _stderr, _wait_thread|
+      stdin.write dot_graph
+      stdin.close
+      return stdout.read
+    end
+  rescue # rubocop:disable Style/RescueStandardError
+    message = "Unable to execute the command 'dot' which is part of graphviz. " \
+      'Ensure that graphviz is installed and that dot is in your path.'
+    puts message
+    message
+  end
+
+  def default_color_for_issue issue
+    {
+      'Story' => '#90EE90',
+      'Task' => '#87CEFA',
+      'Bug' => '#f08080',
+      'Defect' => '#f08080',
+      'Epic' => '#fafad2',
+      'Spike' => '#7fffd4',
+      'Sub-task' => '#dcdcdc'
+    }[issue.type]
+  end
+
+  def shrink_svg svg
+    scale = 0.8
+    svg.sub(/width="([\d.]+)pt" height="([\d.]+)pt"/) do
+      width = $1.to_i * scale
+      height = $2.to_i * scale
+      "width=\"#{width.to_i}pt\" height=\"#{height.to_i}pt\""
+    end
+  end
+
+  def word_wrap text, max_width: 50, separator: '<BR/>'
+    text.chomp.lines.collect do |line|
+      line.chomp!
+
+      # The following characters all cause problems when passed to graphviz
+      line.gsub!(/[{<]/, '[')
+      line.gsub!(/[}>]/, ']')
+      line.gsub!(/\s*&\s*/, ' and ')
+      line.gsub!('|', '')
+
+      if line.length > max_width
+        line.gsub(/(.{1,#{max_width}})(\s+|$)/, "\\1#{separator}").strip
+      else
+        line
+      end
+    end.join(separator)
+  end
+end

data/lib/jirametrics/discard_changes_before.rb

@@ -0,0 +1,37 @@
+# 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/download_config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'date'
+
+class DownloadConfig
+  attr_reader :project_config
+
+  def initialize project_config:, block:
+    @project_config = project_config
+    @block = block
+    @board_ids = []
+  end
+
+  def run
+    instance_eval(&@block)
+  end
+
+  def project_key _key = nil
+    raise 'project, filter, and jql directives are no longer supported. See ' \
+      'https://github.com/mikebowler/jira-export/wiki/Deprecated#project-filter-and-jql-are-no-longer-supported-in-the-download-section'
+  end
+
+  def board_ids *ids
+    deprecated message: 'board_ids in the download block are deprecated. See https://github.com/mikebowler/jira-export/wiki/Deprecated'
+    @board_ids = ids unless ids.empty?
+    @board_ids
+  end
+
+  def filter_name _filter = nil
+    project_key
+  end
+
+  def jql _query = nil
+    project_key
+  end
+
+  def rolling_date_count count = nil
+    @rolling_date_count = count unless count.nil?
+    @rolling_date_count
+  end
+end