gh-issues-stats 0.4.0

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Github
+  class Issues
+    module App
+      ##
+      # Command to show issues created per month in a given year
+      class Month < Base
+        parameter 'YEAR', 'the year to filter by', required: true do |value|
+          Integer(value)
+        end
+        parameter 'REPOSITORY', 'the repository to analyze', required: true
+        option '--format', 'FORMAT', 'specify output format (table, chart, json).', default: 'table'
+        option '--label', 'LABEL', 'filter by label', multivalued: true
+        option '--[no-]finished', :flag, 'show finished stats.', default: false
+        option '--[no-]legend', :flag, 'do not print a legend.', default: true
+        option '--[no-]pager', :flag, 'do not pipe output into a pager.', default: false
+
+        def execute
+          labels = @label_list || []
+          run = exec_run(@repository, @cfgfile, @cachepath, @refresh)
+          issues = exec_load(run, :per_month_filtered_by_labels, [year, labels])
+
+          return exec_bailout('No issues found.') if issues.nil? || issues.empty?
+
+          exec_output(issues, format)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Github
+  class Issues
+    module App
+      ##
+      # Command to show issue stats per year
+      class Year < Base
+        parameter 'REPOSITORY', 'the repository to analyze', required: true
+        option '--format', 'FORMAT', 'specify output format (table, chart, json).', default: 'table'
+        option '--label', 'LABEL', 'filter by label', multivalued: true
+        option '--[no-]finished', :flag, 'show finished stats.', default: false
+        option '--[no-]legend', :flag, 'do not print a legend.', default: true
+        option '--[no-]pager', :flag, 'do not pipe output into a pager.', default: false
+
+        def execute
+          labels = @label_list || []
+          run = exec_run(@repository, @cfgfile, @cachepath, @refresh)
+          issues = exec_load(run, :per_year_filtered_by_labels, [labels])
+
+          return exec_bailout('No issues found.') if issues.nil? || issues.empty?
+
+          average = stats_seconds_to_days(run.all_average_closing_time)
+          median  = stats_seconds_to_days(run.all_median_closing_time)
+          extra   = "#{average} days average closing time. #{median} days median closing time."
+
+          exec_output(issues, format, extra:)
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/app.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'tty-table'
+
+module Github
+  class Issues
+    module App
+      ##
+      # Main command class
+      class Command < Base
+        option '--configuration-file', 'FILE', 'configuration file', attribute_name: :cfgfile
+        option '--cache-path', 'PATH', 'cache path', attribute_name: :cachepath
+        option '--refresh', 'INTERVAL', 'refresh interval (e.g., 30minutes, 2.5hours, 1day)'
+
+        subcommand 'yearly', 'Show issues per year.', Year
+        subcommand 'monthly', 'Show issues per month.', Month
+        subcommand 'labels', 'List all labels.', Labels
+      end
+    end
+  end
+end

data/lib/github/issues/database.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+require 'json'
+require 'time'
+
+module Github
+  class Issues
+    ##
+    # Database class manages the SQLite database for storing GitHub issues
+    class Database
+      include Marshal
+      include Schema
+      include Store
+
+      ##
+      # Database connection handle
+      attr_reader :connection
+
+      ##
+      # Path to the database file
+      attr_reader :path
+
+      ##
+      # Initialize the Database instance
+      #
+      # @param path [String] Path to the SQLite database file
+      #
+      # @return [Github::Issues::Database] Initialized Database instance
+      def initialize(path)
+        @path = path
+        @connection = SQLite3::Database.new(@path)
+        @connection.results_as_hash = true
+
+        schema_create(connection)
+      end
+
+      ##
+      # Close the database connection
+      def close
+        connection.close
+      end
+
+      ##
+      # Store a list of issues and update the last fetch timestamp
+      #
+      # @param issues [Array<Sawyer::Ressource>] List of issues to store
+      # @param timestamp [Time] Timestamp of the fetch operation
+      #
+      # @return [void]
+      def store_issues(issues, timestamp)
+        connection.transaction do
+          issues.each do |issue|
+            store_issue(connection, issue)
+          end
+          store_metadata(connection, 'last_fetch', timestamp.utc.iso8601)
+        end
+      end
+
+      ##
+      # Retrieve all stored issues from the database
+      #
+      # @return [Array<Issues>] List of stored issues
+      def all_issues
+        rows = connection.execute('SELECT * FROM issues ORDER BY created_at DESC')
+        rows.map { |row| marshal_issue(row) }
+      end
+
+      ##
+      # Retrieve all unique labels from the stored issues
+      #
+      # @return [Array<String>] List of unique labels
+      def all_labels
+        rows = connection.execute('SELECT labels FROM issues')
+        label_set = Set.new
+        rows.each do |row|
+          labels = JSON.parse(row['labels'] || '[]')
+          labels.each do |label|
+            label_set.add(label)
+          end
+        end
+        label_set.to_a
+      end
+
+      ##
+      # Count the total number of stored issues
+      #
+      # @return [Integer] Total number of issues
+      def count_issues
+        connection.get_first_value('SELECT COUNT(*) FROM issues')
+      end
+
+      ##
+      # Determine if the database needs to be updated based on the age of the
+      # last fetch timestamp
+      #
+      # @param max_age_seconds [Integer] Maximum age in seconds before the database is considered stale
+      #
+      # @return [Boolean] True if the database needs to be updated, false
+      # otherwise
+      def needs_update?(max_age_seconds = 86_400)
+        timestamp = cache_timestamp
+        return true unless timestamp
+
+        (Time.now - timestamp) >= max_age_seconds
+      end
+
+      ##
+      # Retrieve a metadata value by key
+      #
+      # @param key [String] Metadata key
+      #
+      # @return [String, nil] Metadata value or nil if not found
+      def metadata(key)
+        row = connection.get_first_row('SELECT value FROM metadata WHERE key = ?', key)
+        return nil unless row
+
+        row['value']
+      end
+
+      ##
+      # Retrieve the timestamp of the last fetch operation
+      #
+      # @return [Time, nil] Timestamp of the last fetch or nil if not found
+      def cache_timestamp
+        timestamp_str = metadata('last_fetch')
+        return nil unless timestamp_str
+
+        Time.parse(timestamp_str)
+      end
+    end
+  end
+end

data/lib/github/issues/mixins/database/marshal.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'hashie'
+require 'json'
+require 'time'
+
+module Github
+  class Issues
+    class Database
+      ##
+      # Mixin to marshal issue data from database format to Hashie::Mash
+      module Marshal
+        private
+
+        ##
+        # Marshal issue data from database format to Hashie::Mash
+        #
+        # @param issue [Hash] Issue data from database
+        #
+        # @return [Hashie::Mash] Marshaled issue data
+        def marshal_issue(issue)
+          Hashie::Mash.new(
+            {
+              id: issue['id'],
+              created_at: Time.parse(issue['created_at']),
+              closed_at: issue['closed_at'] ? Time.parse(issue['closed_at']) : nil,
+              number: issue['number'],
+              url: issue['url'],
+              labels: JSON.parse(issue['labels'] || '[]'),
+              state: issue['state']
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/mixins/database/schema.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Github
+  class Issues
+    class Database
+      ##
+      # Mixin for creating database schema
+      module Schema
+        private
+
+        ##
+        # Creates the database schema for issues and metadata tables
+        #
+        # @param connection [SQLite3::Database] Database connection
+        def schema_create(connection)
+          connection.execute <<-SQL
+          CREATE TABLE IF NOT EXISTS issues (
+            id INTEGER PRIMARY KEY,
+            created_at TEXT NOT NULL,
+            closed_at TEXT,
+            number INTEGER UNIQUE NOT NULL,
+            url TEXT NOT NULL,
+            labels TEXT,
+            state TEXT NOT NULL
+          )
+          SQL
+
+          connection.execute <<-SQL
+          CREATE TABLE IF NOT EXISTS metadata (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+          )
+          SQL
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/mixins/database/store.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Github
+  class Issues
+    class Database
+      ##
+      # Mixin for storing issues and metadata in the database
+      module Store
+        private
+
+        ##
+        # Store an issue in the database
+        #
+        # @param connection [SQLite3::Database] Database connection
+        # @param issue [Sawyer::Ressource] Issue to store
+        #
+        # @return [void]
+        def store_issue(connection, issue)
+          if store_issue_exist?(connection, issue.number)
+            store_update_issue(connection, issue)
+          else
+            store_insert_issue(connection, issue)
+          end
+        end
+
+        ##
+        # Store metadata in the database
+        #
+        # @param connection [SQLite3::Database] Database connection
+        # @param key [String] Metadata key
+        # @param value [String] Metadata value
+        #
+        # @return [void]
+        def store_metadata(connection, key, value)
+          connection.execute(
+            'INSERT OR REPLACE INTO metadata (key, value) VALUES (?, ?)',
+            [key, value]
+          )
+        end
+
+        ##
+        # Check if an issue exists in the database
+        #
+        # @param connection [SQLite3::Database] Database connection
+        # @param issue_number [Integer] Issue number
+        #
+        # @return [Boolean] True if the issue exists, false otherwise
+        def store_issue_exist?(connection, issue_number)
+          existing = connection.get_first_row(
+            'SELECT id FROM issues WHERE number = ?',
+            issue_number
+          )
+          !existing.nil?
+        end
+
+        ##
+        # Update an existing issue in the database
+        #
+        # @param connection [SQLite3::Database] Database connection
+        # @param issue [Github::Issue] Issue to update
+        #
+        # @return [void]
+        def store_update_issue(connection, issue)
+          connection.execute(
+            'UPDATE issues SET (created_at, closed_at, url, labels, state) = (?, ?, ?, ?, ?)  WHERE number = ?',
+            [
+              issue.created_at.utc.iso8601,
+              issue.closed_at.nil? ? nil : issue.closed_at.utc.iso8601,
+              issue.html_url,
+              issue.labels.map(&:name).to_json,
+              issue.state,
+              issue.number
+            ]
+          )
+        end
+
+        ##
+        # Insert a new issue into the database
+        #
+        # @param connection [SQLite3::Database] Database connection
+        # @param issue [Github::Issue] Issue to insert
+        #
+        # @return [void]
+        def store_insert_issue(connection, issue)
+          connection.execute(
+            'INSERT INTO issues (created_at, closed_at, url, labels, state, number) VALUES (?, ?, ?, ?, ?, ?)',
+            [
+              issue.created_at.utc.iso8601,
+              issue.closed_at.nil? ? nil : issue.closed_at.utc.iso8601,
+              issue.html_url,
+              issue.labels.map(&:name).to_json,
+              issue.state,
+              issue.number
+            ]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/github/issues/mixins/fetch.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'octokit'
+require 'time'
+
+module Github
+  class Issues
+    ##
+    # Mixin for fetching issues from GitHub and the database
+    module Fetch
+      private
+
+      ##
+      # Ensure the database is up-to-date with issues from GitHub, if the
+      # refresh interval has passed or if there are no issues in the database,
+      # fetch issues from GitHub and update the database
+      #
+      # @param database [Database] Issues database
+      # @param refresh [Integer] Refresh interval in seconds
+      # @param credentials [Hash] GitHub API credentials
+      # @param repository [String] GitHub repository (e.g., 'owner/repo')
+      #
+      # @return [void]
+      def ensure_issues_loaded(database, refresh, credentials, repository)
+        return unless database.needs_update?(refresh) || database.count_issues.zero?
+
+        fetch_and_update_issues(database, credentials, repository)
+      end
+
+      ##
+      # Fetch issues from GitHub and update the database
+      #
+      # @param database [Database] Issues database
+      # @param credentials [Hash] GitHub API credentials
+      # @param repository [String] GitHub repository (e.g., 'owner/repo')
+      #
+      # @return [void]
+      def fetch_and_update_issues(database, credentials, repository)
+        cached_timestamp = database.cache_timestamp
+        fetch_timestamp = Time.now
+
+        if cached_timestamp
+          new_issues = fetch_issues_from_github(
+            credentials,
+            repository,
+            since: cached_timestamp
+          )
+
+          database.store_issues(new_issues, fetch_timestamp) unless new_issues.empty?
+        else
+          all_issues = fetch_issues_from_github(credentials, repository)
+          database.store_issues(all_issues, fetch_timestamp)
+        end
+      end
+
+      ##
+      # Fetch issues from GitHub
+      #
+      # @param credentials [Hash] GitHub API credentials
+      # @param repository [String] GitHub repository (e.g., 'owner/repo')
+      # @param since [Time, nil] Optional timestamp to fetch issues updated since this time
+      #
+      # @return [Array<Sawyer::Resource>] The fetched issues
+      def fetch_issues_from_github(credentials, repository, since: nil)
+        octokit = Octokit::Client.new(credentials)
+        octokit.auto_paginate = true
+
+        options = {
+          state: 'all',
+          sort: 'created',
+          direction: 'desc'
+        }
+        options[:since] = since.utc.iso8601 if since
+
+        octokit.issues(repository, options)
+               .reject { |issue| issue.pull_request || issue.draft }
+      end
+
+      ##
+      # Check if a GitHub repository exists
+      #
+      # @param credentials [Hash] GitHub API credentials
+      # @param repository [String] GitHub repository (e.g., 'owner/repo')
+      #
+      # @return [void]
+      def github_repository_exist!(credentials, repository)
+        octokit = Octokit::Client.new(credentials)
+        octokit.repository(repository)
+
+        nil
+      end
+
+      ##
+      # Fetch issues from the database applying the given labels filter
+      #
+      # @param database [Database] Issues database
+      # @param labels [Array<String>, nil] Labels to filter issues by
+      #
+      # @return [Array<Hashie::Mash>] Filtered issues
+      def fetch_issues_from_database(database, labels: nil)
+        return database.all_issues if labels.nil? || labels.empty?
+
+        include_labels, exclude_labels = group_include_exclude_labels(labels)
+
+        database.all_issues.select do |issue|
+          has_includes = include_labels.all? { |label| issue.labels.include?(label) }
+          has_excludes = exclude_labels.any? { |label| issue.labels.include?(label) }
+          has_includes && !has_excludes
+        end
+      end
+
+      ##
+      # Separating include and exclude labels
+      #
+      # @param labels [Array<String>] Labels to filter issues by
+      #
+      # @return [Array<Array<String>, Array<String>>] Include and exclude labels
+      def group_include_exclude_labels(labels)
+        include_labels = labels.reject { |label| label.start_with?('!') }
+        exclude_labels = labels.select { |label| label.start_with?('!') }.map { |label| label[1..] }
+
+        [include_labels, exclude_labels]
+      end
+    end
+  end
+end

data/lib/github/issues/mixins/group.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Github
+  class Issues
+    ##
+    # Mixin for grouping issues by time periods
+    module Group
+      private
+
+      ##
+      # Groups issues by a given period (:year, :month) and returns a hash with
+      # keys as period values and values as hashes containing arrays of
+      # created, closed, finished, and open issues
+      #
+      # @param list [Array<Hashie::Mash>] List of issues to group
+      # @param period [Symbol] Period to group by (:year or :month)
+      #
+      # @return [Hashie::Mash]
+      def group_by_period(list, period: :year)
+        created  = list.group_by { |issue| issue.created_at.send(period) }
+        created  = group_compact(created)
+
+        closed   = list.group_by { |issue| issue.closed_at&.send(period) }
+        closed   = group_compact(closed)
+
+        finished = list.select do |issue|
+          issue.state == 'closed' && issue.created_at.send(period) == issue.closed_at.send(period)
+        end
+        finished = finished.group_by { |issue| issue.created_at.send(period) }
+        finished = group_compact(finished)
+
+        open = group_open_issues(list, period)
+        open = group_compact(open)
+
+        group_merge(created, closed, finished, open)
+      end
+
+      ##
+      # Group compaction helper removes nil keys and ensures no nil values in
+      # the group hash
+      #
+      # @param group [Hashie::Mash] Group of issues
+      #
+      # @return [Hashie::Mash]
+      def group_compact(group)
+        group = group.reject { |k, _| k.nil? }
+        group.each { |k, v| group[k] = [] if v.nil? }
+
+        group
+      end
+
+      ##
+      # Groups open issues by period - issues that are still open at the end of the period
+      #
+      # @param list [Array<Hashie::Mash>] List of issues
+      # @param period [Symbol] Period to group by (:year or :month)
+      #
+      # @return [Hash] Group of open issues by period
+      def group_open_issues(list, period)
+        open_by_period = {}
+
+        list.each do |issue|
+          created_period = issue.created_at.send(period)
+
+          if issue.state == 'open'
+            open_by_period[created_period] ||= []
+            open_by_period[created_period] << issue
+          elsif issue.closed_at
+            closed_period = issue.closed_at.send(period)
+            if created_period != closed_period
+              open_by_period[created_period] ||= []
+              open_by_period[created_period] << issue
+            end
+          end
+        end
+
+        open_by_period
+      end
+
+      ##
+      # Merges created, closed, finished, and open issue groups into a single hash
+      # ensuring all keys are present in the final hash
+      #
+      # @param created [Hashie::Mash] Group of created issues
+      # @param closed [Hashie::Mash] Group of closed issues
+      # @param finished [Hashie::Mash] Group of finished issues
+      # @param open [Hashie::Mash] Group of open issues
+      #
+      # @return [Hashie::Mash] Merged group of issues
+      def group_merge(created, closed, finished, open)
+        keys = created.keys | closed.keys | finished.keys | open.keys
+        keys.sort!.reverse!
+
+        keys.each_with_object({}) do |key, hash|
+          hash[key] = {
+            created: created[key] || [],
+            closed: closed[key] || [],
+            finished: finished[key] || [],
+            open: open[key] || []
+          }
+        end
+      end
+    end
+  end
+end