gh-issues-stats 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c2e4b26d292367033205a9d9e60877b5e62835d3ff1125749fc7755c21605c6
+  data.tar.gz: 11126d3e881cc2f48c2eda51f7a64dd9c3df6a096cd64915fe75babd3f6e1742
+SHA512:
+  metadata.gz: 4c824e6748a0c2eb65ffdf684dc6b0631fc051cf5613a8df2ff1b157c8692ef4b087832d5b1e5076f8b05b335c2c2820dceae6af2c139cfc0dbf6b501794bccb
+  data.tar.gz: 74d4fb1b10b3e36cccb03e6d046347866c1939dd78fdeb5b139002c04f4f97bc5017c96c1cd77813f2c38c545d94d88086561528412cee024f70f9916cf47cd8

data/bin/gh-issues-stats

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'gh-issues-stats'
+
+Github::Issues::App::Command.run

data/lib/gh-issues-stats.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.inflector.inflect(
+  'gh-issues-stats' => 'Github',
+  'version' => 'VERSION'
+)
+loader.collapse("#{__dir__}/github/issues/mixins")
+loader.collapse("#{__dir__}/github/issues/app/mixins")
+loader.setup
+
+##
+# Namespace for Github modules
+module Github; end

data/lib/github/issues/app/base.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'clamp'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Base command class
+      #
+      # Inherits from Clamp::Command and includes mixins and is inherited by
+      # the specific command classes
+      class Base < Clamp::Command
+        include Github::Issues::App::Chart
+        include Github::Issues::App::Exec
+        include Github::Issues::App::Legend
+        include Github::Issues::App::Options
+        include Github::Issues::App::Statistics
+        include Github::Issues::App::Table
+
+        option ['-m', '--man'], :flag, 'show manpage' do # rubocop:disable Metrics/BlockLength
+          manpage = <<~MANPAGE
+            Name:
+                gh-issues-stats - Analyse Github repository issues lifecycle.
+
+            #{help}
+
+            Description:
+                gh-issues-stats is a command-line tool that helps you analyze and
+                understand the issues lifecycle in any GitHub repository. It provides
+                detailed statistics, visualizations, and insights about issues including:
+
+                - Issue creation trends over time (yearly/monthly breakdowns)
+                - Closing time statistics (average and median)
+                - Label-based filtering and analysis
+                - Visual charts and tables for data representation
+                - Cached data for faster subsequent queries
+
+            Commands:
+                yearly REPOSITORY
+                    Display yearly statistics for a repository.
+
+                monthly YEAR REPOSITORY
+                    Display monthly statistics for a specific year.
+
+                labels REPOSITORY
+                    Display all labels used in a repository.
+
+            Options:
+                --configuration-file FILE
+                    Specify a configuration file (default: ~/.config/gh-issues-stats.json)
+
+                --cache-path PATH
+                    Specify cache path (default: ~/.cache/gh-issues-stats)
+
+                --refresh INTERVAL
+                    Set refresh interval (e.g., 30minutes, 2.5hours, 1day) (default: 24hours)
+
+                --label LABEL
+                    Filter by specific label (can be used multiple times; prefix with '!' to exclude)
+
+                --[no-]finished
+                    Show finished stats (default: false) (statistics about created and closed issues in the same period)
+
+                --[no-]legend
+                    Toggle legend display (default: true)
+
+                --[no-]pager
+                    Toggle output paging (default: false)
+
+                --[no-]chart
+                    Show bar chart instead of table (default: false)
+
+                -v, --version
+                    Show version information
+
+                -m, --man
+                    Show this manual page
+
+            Examples:
+                Display yearly statistics for a repository:
+                    $ gh-issues-stats yearly rails/rails
+
+                Display monthly statistics for a specific year:
+                    $ gh-issues-stats monthly 2023 rails/rails
+
+                Filter issues by multiple labels:
+                    $ gh-issues-stats yearly rails/rails --label bug --label '!enhancement'
+
+                Show monthly breakdown with chart visualization:
+                    $ gh-issues-stats monthly 2023 rails/rails --chart
+
+                Use with custom refresh interval:
+                    $ gh-issues-stats yearly rails/rails --refresh 2hours
+
+                List all labels in a repository:
+                    $ gh-issues-stats labels rails/rails
+
+            Configuration:
+                For higher API rate limits, you can provide GitHub credentials through
+                a JSON configuration file. The configuration file will be loaded from
+                the path specified via --configuration-file (default: ~/.config/gh-issues-stats.json).
+
+            Caching:
+                Issue data is cached locally in the specified cache path --cache-path
+                (default: ~/.cache/gh-issues-stats) to improve performance on subsequent
+                queries. The cache is automatically refreshed based on the refresh interval
+                (default: 24 hours).
+
+            Author:
+                Tobias Schäfer <github@blackox.org>
+
+            Homepage:
+                https://github.com/tschaefer/gh-issues-stats
+          MANPAGE
+          TTY::Pager.page(manpage)
+
+          exit 0
+        end
+
+        option ['-v', '--version'], :flag, 'show version' do
+          puts "gh-issues-stats #{Github::Issues::VERSION}"
+          exit 0
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/labels.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'tty-table'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Command to list labels in a repository
+      class Labels < Base
+        TABLE_COLUMNS = 3
+
+        parameter 'REPOSITORY', 'the repository to analyze', required: true
+        option '--json', :flag, 'output in JSON format', default: false, attribute_name: :structured
+
+        def execute
+          run = exec_run(@repository, @cfgfile, @cachepath, @refresh)
+          labels = exec_load(run, :labels, [])
+
+          if structured?
+            puts JSON.pretty_generate(labels)
+            return
+          end
+
+          rows = []
+          labels.each_slice(TABLE_COLUMNS) do |slice|
+            (TABLE_COLUMNS - slice.size).times { slice << '' } if slice.size < TABLE_COLUMNS
+            rows << slice
+          end
+          table = TTY::Table.new(rows: rows)
+          puts table.render(border_class: TTY::Table::Border::Null, resize: true, multiline: true)
+          puts "\nTotal labels: #{labels.size}"
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/mixins/chart.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'hashie/mash'
+require 'unicode_plot'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Mixin to create charts for issues data
+      module Chart
+        private
+
+        ##
+        # Create charts for the given issues data
+        #
+        # @param issues [Hashie::Mash] Issues data
+        #
+        # @return [String] Rendered charts
+        def chart_create(issues)
+          values = chart_determine_values(issues)
+
+          if %w[true 1].include?(ENV.fetch('NO_COLOR', 'false').upcase)
+            "#{chart_plot_created(values)}\n\n" \
+              "#{chart_plot_closed(values)}\n\n" \
+              "#{chart_plot_open(values)}\n\n" \
+              "#{chart_plot_created_closed_ratio(values)}"
+          else
+            chart_plot_created(values).render
+            chart_plot_closed(values).render
+            chart_plot_open(values).render
+            chart_plot_created_closed_ratio(values).render
+          end
+        end
+
+        def chart_determine_values(issues)
+          values = Hashie::Mash.new(
+            {
+              labels: [],
+              created_counts: [],
+              closed_counts: [],
+              open_counts: [],
+              created_closed_ratios: []
+            }
+          )
+
+          issues.each do |period, data|
+            values.labels << period.to_s
+            values.created_counts << (data.created&.size || 0)
+            values.closed_counts << (data.closed&.size || 0)
+            values.open_counts << (data.open&.size || 0)
+            values.created_closed_ratios << data.stats.ratio.all.round(2)
+          end
+
+          values
+        end
+
+        ##
+        # Create the created issues barplot
+        #
+        # @return [UnicodePlot::Barplot] Created issues barplot
+        def chart_plot_created(data)
+          UnicodePlot.barplot(
+            data.labels,
+            data.created_counts,
+            title: 'Created',
+            color: :red,
+            width: 60
+          )
+        end
+
+        ##
+        # Create the closed issues barplot
+        #
+        # @return [UnicodePlot::Barplot] Closed issues barplot
+        def chart_plot_closed(data)
+          UnicodePlot.barplot(
+            data.labels,
+            data.closed_counts,
+            title: 'Closed',
+            color: :green,
+            width: 60
+          )
+        end
+
+        ##
+        # Create the open issues barplot
+        #
+        # @return [UnicodePlot::Barplot] Open issues barplot
+        def chart_plot_open(data)
+          UnicodePlot.barplot(
+            data.labels,
+            data.open_counts,
+            title: 'Open',
+            color: :yellow,
+            width: 60
+          )
+        end
+
+        ##
+        # Create the created/closed ratio barplot
+        #
+        # @return [UnicodePlot::Barplot] Created/Closed ratio barplot
+        def chart_plot_created_closed_ratio(data)
+          UnicodePlot.barplot(
+            data.labels,
+            data.created_closed_ratios,
+            title: 'Created/Closed Ratio',
+            color: :blue,
+            width: 60
+          )
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/mixins/exec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'pastel'
+require 'tty-pager'
+require 'tty-spinner'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Mixin for execution methods
+      module Exec
+        private
+
+        ##
+        # Bail out of execution with an error message
+        #
+        # @param message [String] Error message to display
+        def exec_bailout(message)
+          warn Pastel.new.red.bold(message)
+          exit 1
+        end
+
+        ##
+        # Initialize and return the GitHub Issues instance
+        #
+        # @param repository [String] GitHub repository in 'owner/repo' format
+        # @param config_file [String, nil] Path to the configuration file
+        # @param refresh_interval [String, nil] Refresh interval for caching
+        #
+        # @return [Github::Issues] Initialized GitHub Issues instance
+        def exec_run(repository, config_file, cache_path, refresh_interval)
+          Github::Issues.new(
+            repository,
+            credentials: options_parse_configuration(config_file),
+            refresh: options_parse_refresh_interval(refresh_interval),
+            cache: options_parse_cache_path(cache_path)
+          )
+        rescue Octokit::NotFound
+          exec_bailout("Repository '#{repository}' not found.")
+        rescue StandardError => e
+          exec_bailout(e.message)
+        end
+
+        ##
+        # Execute the specified method on the GitHub Issues instance with a
+        # loading spinner
+        #
+        # @param run [Github::Issues] GitHub Issues instance
+        # @param method [Symbol] Method to call on the instance
+        # @param args [Array] Arguments to pass to the method
+        #
+        # @return [Object] Result of the method call
+        def exec_load(run, method, args)
+          results = nil
+          spinner = TTY::Spinner.new(':spinner Fetching data ...', format: :dots, clear: true)
+          spinner.run("Done.\n") do
+            results = run.send(method, *args)
+          end
+
+          results
+        end
+
+        ##
+        # Generate and display the output based on the specified format
+        #
+        # @param issues [Hashie::Mash] List of issues to display
+        # @param format [String] Output format ('table', 'chart', 'json')
+        # @param extra [Hash, nil] Extra information for the legend
+        #
+        # @return [void]
+        def exec_output(issues, format, extra: nil)
+          content = case format
+                    when 'table' then table_create(issues, finished?)
+                    when 'chart' then chart_create(issues)
+                    when 'json'  then return puts JSON.pretty_generate(issues)
+                    else exec_bailout("Unsupported output format: #{format}")
+                    end
+          legend = legend_create(issues, legend?, extra:)
+
+          TTY::Pager.new(enabled: pager?).page("#{content}#{legend}")
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/mixins/legend.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Github
+  class Issues
+    module App
+      ##
+      # Mixin for legend creation
+      module Legend
+        private
+
+        ##
+        # Create a legend for the issues report
+        #
+        # @param issues [Array<Hash>] Issues data
+        # @param extra [String, nil] Extra information to include in the legend
+        #
+        # @return [String] Legend string
+        def legend_create(issues, legend, extra: nil)
+          return "\n" unless legend
+
+          created = 0
+          closed = 0
+          open = 0
+          issues.each do |group|
+            data = group.last
+
+            created += data[:created].size
+            closed += data[:closed].size
+            open += data[:created].size - data[:closed].size
+          end
+
+          legend = "\n\n#{created} created. #{closed} closed. #{open} open."
+          legend = "#{legend}\n#{extra}" if extra
+
+          "#{legend}\n"
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/mixins/options.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Mixin for option parsing methods
+      module Options
+        DEFAULT_CONFIG_FILE = File.join(Dir.home, '.config/gh-issues-stats.json').freeze
+
+        private
+
+        ##
+        # Parse refresh interval option and transforms strings like
+        # '30minutes', '2hours', '1day' into seconds
+        #
+        # @param interval [String, nil] Refresh interval string
+        #
+        # @return [Float] Refresh interval in seconds
+        def options_parse_refresh_interval(interval)
+          interval ||= '24hours'
+          match = interval.match(/^(\d+(?:\.\d+)?)(seconds?|minutes?|hours?|days?)$/)
+
+          unless match
+            raise "Invalid refresh interval format: '#{interval}'. " \
+                  "Use format like '30minutes', '2hours', '1day'"
+          end
+
+          value = match[1].to_f
+          unit = match[2]
+
+          case unit
+          when /^seconds?$/
+            value
+          when /^minutes?$/
+            value * 60
+          when /^hours?$/
+            value * 60 * 60
+          when /^days?$/
+            value * 60 * 60 * 24
+          else
+            raise "Unknown time unit: #{unit}"
+          end
+        end
+
+        ##
+        # Parse configuration file option and loads JSON configuration from the
+        # specified file or default location
+        #
+        # @param file [String, nil] Path to configuration file
+        #
+        # @return [Hash] Configuration options
+        def options_parse_configuration(file)
+          file ||= DEFAULT_CONFIG_FILE
+          File.exist?(file) ? JSON.load_file(file).transform_keys(&:to_sym) : {}
+        rescue JSON::ParserError
+          raise "Failed to parse configuration file '#{file}'"
+        end
+
+        ##
+        # Parse cache path option and returns the specified path or
+        # a default cache path
+        #
+        # @param path [String, nil] Path to cache directory
+        #
+        # @return [String] Cache directory path
+        def options_parse_cache_path(path)
+          path || File.join(Dir.home, '.cache', 'gh-issues-stats')
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/mixins/statistics.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'hashie'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Mixin for statistics methods
+      module Statistics
+        private
+
+        ##
+        # Convert stats closing time from seconds to days
+        #
+        # @param stats [Hashie::Mash] Statistics data
+        #
+        # @return [Hashie::Mash] Statistics data with time in days
+        def stats_as_days(stats)
+          Hashie::Mash.new(
+            {
+              all_avg: stats_seconds_to_days(stats.close_time.all.average),
+              all_median: stats_seconds_to_days(stats.close_time.all.median),
+              finished_avg: stats_seconds_to_days(stats.close_time.finished.average),
+              finished_median: stats_seconds_to_days(stats.close_time.finished.median)
+            }
+          )
+        end
+
+        ##
+        # Convert seconds to days
+        #
+        # @param seconds [Integer] Time in seconds
+        #
+        # @return [Integer] Time in days
+        def stats_seconds_to_days(seconds)
+          (seconds / 60 / 60 / 24).round
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app/mixins/table.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'tty-table'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Mixin for table rendering
+      module Table
+        private
+
+        ##
+        # Renders the table for the issues statistics
+        #
+        # @param issues [Hash::Mash] Issues statistics data
+        # @param finished [Boolean] Whether to include finished issues statistics
+        #
+        # @return [String] Rendered table as a string
+        def table_create(issues, finished)
+          header = table_header_create(finished)
+
+          rows = issues.map do |year, data|
+            table_row_create(year, data, finished)
+          end
+          table = TTY::Table.new(header, rows)
+
+          table.render(multiline: true, width: 2**16) do |renderer|
+            renderer.border do
+              mid     '─'
+              mid_mid '─'
+              center  ' '
+            end
+          end
+        end
+
+        ##
+        # Creates the table header
+        #
+        # @param finished [Boolean] Whether to include finished issues statistics
+        #
+        # @return [Array<String>] Table header
+        def table_header_create(finished)
+          period = self.class.name.split('::').last.sub('Command', '')
+          header = [
+            period
+          ]
+
+          header += %w[
+            Created
+            Closed
+            Open
+            Created-Closed-Ratio
+            Closed-Avg
+            Closed-Median
+          ]
+
+          return header unless finished
+
+          header + %w[
+            Finished
+            Finished-Ratio
+            Finished-Avg
+            Finished-Median
+          ]
+        end
+
+        ##
+        # Creates a table row for a given period and data
+        #
+        # @param period [String] Period (year, month as integer)
+        # @param data [Hash::Mash] Period data
+        # @param finished [Boolean] Whether to include finished issues
+        #
+        # @return [Array] Table row
+        def table_row_create(period, data, finished)
+          stats = stats_as_days(data.stats)
+          all = [
+            period,
+            data.created&.size || 0,
+            data.closed&.size || 0,
+            data.open&.size || 0,
+            data.stats.ratio.all.round(2),
+            stats.all_avg,
+            stats.all_median
+          ]
+
+          all += table_row_finished_create(data) if finished
+
+          all
+        end
+
+        ##
+        # Creates the finished issues statistics for a table row
+        # @param data [Hash::Mash] Period data
+        #
+        # @return [Array] Finished issues statistics
+        def table_row_finished_create(data)
+          [
+            data.finished&.size || 0,
+            data.stats.ratio.finished.round(2),
+            stats_seconds_to_days(data.stats.close_time.finished.average),
+            stats_seconds_to_days(data.stats.close_time.finished.median)
+          ]
+        end
+      end
+    end
+  end
+end