oss-stats 0.0.1

data/docs/RepoStats.md

@@ -0,0 +1,130 @@
+# Repo Stats
+
+[repo_stats](../bin/repo_stats.rb) is a tool designed to give a wide range of
+statistics on everything from PRs response time to CI health. It supports both
+GitHub and Buildkite and is highly configurable.
+
+It will walk all configured repos in all configured organizations and gather
+the desired statistics and print them out in Slack-friendly Markdown.
+
+The tool has 3 modes, and by default runs all 3 (aka `all` mode):
+
+* CI
+* PR
+* Issue
+
+For each mode, it pulls statistics for the last N days (default: 30).
+
+We'll look at each mode in detail in the sections below.
+
+**NOTE**: These examples specify a single GH Organization and GH Repository on
+the command line, but most people will want to use the configuration file to
+configure a list of org/repos to walk.
+
+## CI mode
+
+The CI mode walks all CI related to the repositires in question and reports
+the number of days they were broken on each branch desired (default: main).
+
+It discovers both GitHub Actions workflows as well as Buildkite Pipelines.  For
+Buildkite pipelines, the tool will pull all pipelines in the specified
+Buildkite Organization and map them to GitHub repos. In addition, it'll check
+the README on every repo it examines and look for any badges that point to a
+Buildkite pipeline and attempt to pull status of that (even if it is in a
+different Buildkite organization).
+
+For a single repository with both GitHub and Buildkite checks, this is
+sample output:
+
+```markdown
+*_[chef/chef](https://github.com/chef/chef) Stats (Last 7 days)_*
+
+* CI Stats:
+    * Branch: `main` has the following failures:
+        * Dependabot Updates / Dependabot: 5 days
+        * [BK] chef-oss/chef-chef-main-habitat-test: 3 days
+        * [BK] chef-oss/chef-chef-main-verify: 3 days
+```
+
+If there is no `--buildkite-org` passed in, no attempt will be made to find
+or check any Buildkite pipelines.
+
+## PR and Issues modes
+
+These modes work the same way, but report on PRs or Issues, respectively.
+They gather a variety of statistics, and here's some sample output when
+both modes are active:
+
+```markdown
+*_[chef/chef](https://github.com/chef/chef) Stats (Last 7 days)_*
+
+* PR Stats:
+    * Closed PRs: 5
+    * Open PRs: 38 (6 opened this period)
+    * Oldest Open PR: 2025-03-03 (103 days open, last activity 84 days ago)
+    * Stale PR (>30 days without comment): 15
+    * Avg Time to Close PRs: 3.02 days
+
+* Issue Stats:
+    * Closed Issues: 0
+    * Open Issues: 8 (1 opened this period)
+    * Oldest Open Issue: 2025-03-06 (100 days open, last activity 72 days ago)
+    * Stale Issue (>30 days without comment): 5
+    * Avg Time to Close Issues: 0 hours
+```
+
+## Configuration File
+
+Unless you only have single repository you're interested in, you'll need to
+make a configuration file if you don't want to have to run `repo_stats`
+repeatedly. It allows you to specify orgs, repos within those orgs, and
+customize branches to check and days to report on by repo.
+
+See [examples/repo_stats_config.rb](../examples/repo_stats_config.rb) for details.
+
+## Threshold Filtering
+
+When working with a large number of repositories, the output of `repo_stats.rb`
+can become quite verbose. Threshold filtering options allow you to narrow down
+the report to include only the top N or N% of repositories based on specific
+criteria. This helps in identifying areas that might need the most attention.
+
+If multiple threshold options are provided, repositories meeting *any* of the
+specified criteria will be included in the report.
+
+Percentages (`N%`) are calculated based on the total number of repositories
+being processed in the current run. For example, if 20 repositories are being
+processed and `--top-n-stale=10%` is used, the top 2 repositories (10% of 20)
+will be selected for that criterion.
+
+The following threshold filtering options are available:
+
+* `--top-n-stale=N` or `N%`: Includes the top N or N% of repositories based
+  on the *maximum* stale count of either its Pull Requests or Issues (stale
+  is defined as >30 days without a comment). For example, if a repo has 5
+  stale PRs and 10 stale Issues, it's ranked by 10.
+* `--top-n-oldest=N` or `N%`: Includes the top N or N% of repositories with
+  the oldest open item (Pull Request or Issue). The age of the single oldest
+  item (be it a PR or an Issue) in a repository is used for comparison.
+* `--top-n-time-to-close=N` or `N%`: Includes the top N or N% of repositories
+  with the highest average time-to-close. The ranking uses the *higher* of
+  the average time-to-close for Pull Requests or the average time-to-close
+  for Issues within a repository.
+* `--top-n-stale-pr=N` or `N%`: Includes the top N or N% of repositories with
+  the most stale Pull Requests.
+* `--top-n-stale-issue=N` or `N%`: Includes the top N or N% of repositories
+  with the most stale Issues.
+* `--top-n-oldest-pr=N` or `N%`: Includes the top N or N% of repositories
+  with the oldest open Pull Requests.
+* `--top-n-oldest-issue=N` or `N%`: Includes the top N or N% of repositories
+  with the oldest open Issues.
+* `--top-n-time-to-close-pr=N` or `N%`: Includes the top N or N% of
+  repositories with the highest average time-to-close for Pull Requests.
+* `--top-n-time-to-close-issue=N` or `N%`: Includes the top N or N% of
+  repositories with the highest average time-to-close for Issues.
+* `--top-n-most-broken-ci-days=N` or `N%`: Includes the top N or N% of
+  repositories with the highest total number of days CI jobs were reported as
+  broken across all checked branches.
+* `--top-n-most-broken-ci-jobs=N` or `N%`: Includes the top N or N% of
+  repositories with the highest number of distinct CI jobs that were reported
+  as broken across all checked branches.

data/examples/meeting_stats_config.rb

@@ -0,0 +1,22 @@
+db_file DEFAULT_DB_FILE = File.expand_path(
+  './data/meeting_data.sqlite3',
+  __dir__,
+)
+output File.expand_path('./team_meeting_reports.md', __dir__)
+image_dir File.expand_path('./images', __dir__)
+teams [
+  'Client',
+  'Server',
+  'Core Libs',
+]
+header <<~EOF
+    # Slack Meeting tracking
+
+    some stuff here...
+
+    ## Trends
+
+    [![Attendance](images/attendance-small.png)](images/attendance-full.png)
+    [![Build Status
+       Reports](images/build_status-small.png)](images/build_status-full.png)
+EOF

data/examples/promise_stats_config.rb

@@ -0,0 +1,23 @@
+# Example promise_stats config file.
+#
+# You can specify anything in here you can specify on the command-line
+# except for --date, --promise, and --reference.
+
+db_file DEFAULT_DB_FILE = File.expand_path(
+  './data/promises.sqlite3',
+  __dir__,
+)
+header <<~EOF
+    # Promises Report #{Date.today.to_s}
+EOF
+
+# Uncomment this and set it to a string to have the output
+# of this script written to a file.
+#
+# output nil
+
+# Uncomment to change the default log level
+# log_level :info
+
+# Uncomment to include promises marked 'abandoned' in status output
+# include_abandoned false

data/examples/repo_stats_config.rb

@@ -0,0 +1,49 @@
+# Example configuration file for repo_stats
+
+# You can specify branches for specific repos under 'organizations'
+# below, but for anything not specified it'll use `default_branches`
+# (which defaults to ['main'])
+#
+# Note do NOT set 'days' or 'branches' in your config, as that overrides
+# everything and is meant for CLI options.
+default_branches %w{main v2}
+default_days 30
+# you can specify 'days', but it will override everything, including
+# anything repo-specific below, so don't do that.
+log_level :info
+ci_timeout 600
+include_list false
+
+# the most interesting part about this config file
+# is the organizations block. It allows you to specify
+# all of the repos that will be processed and how
+# they should be processed
+organizations({
+  'someorg' => {
+    # if this org uses different branches (can further override under the repo)
+    'branches' => ['trunk'],
+    # if you want a different number of days by for repos in this org (can
+    # further override under the repo)
+    'days' => 7,
+    'repositories' => {
+      'repo1' => {},
+      'repo2' => {
+        # crazy repo, only do 2 days
+        'days' => 2,
+        'branches' => ['main'],
+      },
+      'repo3' => {
+        'days' => 30,
+        'branches' => ['main'],
+      }
+  },
+  'anotherorg' => {
+    'days' => 45,
+    'branches' => %w{main oldstuff},
+    'repositories' => {
+      'repo1' => {},
+      'repo2' => {},
+      'repo3' => {},
+    },
+  },
+})

data/initialization_data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+eval_gemfile('../oss-stats/Gemfile')

data/initialization_data/README.md

@@ -0,0 +1,20 @@
+# OSS Stats for <Project>
+
+This repo aims to track stats that affect how <project>'s open source community
+interacts with the project and repositories.
+
+It leverages [oss-stats](https://github.com/jaymzh/oss-stats) to track those
+stats. It assumes oss-stats and this repo are checked out next to each other
+on the filesystem.
+
+## tl;dr
+
+* See **Issue, PR, and CI stats** in [ci_reports](ci_reports)
+* See **weekly meeting stats** in [Slack Status Tracking](team_slack_reports.md)
+* See **pipeline visiblity stats** in [pipeline_visibility_reports](pipeline_visibility_reports)
+* See **promises** in [promises][promises]
+
+## Usage
+
+For updated information on using these scripts see the [oss-stats
+README](https://github.com/jaymzh/oss-stats/blob/main/README.md).

data/initialization_data/rubocop.yml

@@ -0,0 +1,2 @@
+inherit_from:
+  - ../oss-stats/.rubocop.yml

data/lib/oss_stats/buildkite_client.rb

@@ -0,0 +1,252 @@
+require 'net/http'
+require 'json'
+require 'uri'
+
+require_relative 'log'
+
+module OssStats
+  # Client for interacting with the Buildkite GraphQL API.
+  class BuildkiteClient
+    attr_reader :token, :organization_slug
+
+    # Initializes a new BuildkiteClient.
+    #
+    # @param token [String] The Buildkite API token.
+    # @param organization_slug [String] The slug of the Buildkite organization.
+
+    def initialize(token)
+      @token = token
+      @graphql_endpoint = URI('https://graphql.buildkite.com/v1')
+    end
+
+    def get_pipeline(org, pipeline)
+      log.debug("Fetching pipeline: #{org}/#{pipeline}")
+      query = <<~GRAPHQL
+        query {
+          pipeline(slug: "#{org}/#{pipeline}") {
+            visibility
+            url
+          }
+        }
+      GRAPHQL
+
+      response_data = execute_graphql_query(query)
+      pipeline_data = response_data.dig('data', 'pipeline')
+      if pipeline_data.nil? && response_data['data'].key?('pipeline')
+        # The query returned, and the 'pipeline' key exists but is null,
+        # meaning the pipeline was not found by Buildkite.
+        log.debug(
+          "Pipeline #{org}/#{pipeline} not found.",
+        )
+      elsif pipeline_data.nil? && response_data['errors']
+        # Errors occurred, already logged by execute_graphql_query,
+        # but we might want to note the slug it failed for.
+        log.warn(
+          "Failed to fetch pipeline #{org}/#{pipeline}" +
+          'due to API errors',
+        )
+      end
+      pipeline_data
+    rescue StandardError => e
+      log.error(
+        "Error in get_pipeline for slug #{org}/#{pipeline}: #{e.message}",
+      )
+      nil
+    end
+
+    def all_pipelines(org)
+      log.debug("Fetching all pipeline in #{org}")
+      pipelines = []
+      after_cursor = nil
+      has_next_page = true
+
+      while has_next_page
+        query = <<~GRAPHQL
+          query {
+            organization(slug: "#{org}") {
+              pipelines(
+                first: 50,
+                after: #{after_cursor ? "\"#{after_cursor}\"" : 'null'}
+              ) {
+                edges {
+                  node {
+                    slug
+                    repository {
+                      url
+                    }
+                    visibility
+                    url
+                  }
+                }
+                pageInfo {
+                  endCursor
+                  hasNextPage
+                }
+              }
+            }
+          }
+        GRAPHQL
+
+        response_data = execute_graphql_query(query)
+        current_pipelines = response_data.dig(
+          'data', 'organization', 'pipelines', 'edges'
+        )
+        if current_pipelines
+          pipelines.concat(
+            current_pipelines.map { |edge| edge['node'] },
+          )
+        end
+
+        page_info = response_data.dig(
+          'data', 'organization', 'pipelines', 'pageInfo'
+        )
+        break unless page_info
+        has_next_page = page_info['hasNextPage']
+        after_cursor = page_info['endCursor']
+      end
+
+      pipelines
+    end
+
+    def pipelines_by_repo(org)
+      log.debug("pipelines_by_repo: #{org}")
+      pipelines_by_repo = Hash.new { |h, k| h[k] = [] }
+      all_pipelines(org).each do |pipeline|
+        repo_url = pipeline.dig('repository', 'url').gsub('.git', '')
+        next unless repo_url
+
+        pipelines_by_repo[repo_url] << {
+          slug: pipeline['slug'],
+          url: pipeline['url'],
+          visibility: pipeline['visibility'],
+        }
+      end
+
+      pipelines_by_repo
+    end
+
+    # Fetches builds for a given pipeline within a specified date range.
+    # Handles pagination to retrieve all relevant builds.
+    #
+    # @param pipeline_slug [String] The slug of the pipeline
+    #   (without the organization part).
+    # @param from_date [Date] The start date for fetching builds.
+    # @param to_date [Date] The end date for fetching builds.
+    # @return [Array<Hash>] An array of build edges from the GraphQL response.
+    #   Each edge contains a 'node' with build details including 'state',
+    #   'createdAt', and 'jobs'.
+    #   Returns an empty array if an error occurs or no builds are found.
+    def get_pipeline_builds(org, pipeline, from_date, to_date, branch = 'main')
+      log.debug("get_pipeline_builds: #{org}, #{pipeline}")
+      all_build_edges = []
+      after_cursor = nil
+      has_next_page = true
+
+      while has_next_page
+        query = <<~GRAPHQL
+          query {
+            pipeline(slug: "#{org}/#{pipeline}") {
+              builds(
+                first: 50,
+                after: #{after_cursor ? "\"#{after_cursor}\"" : 'null'},
+                createdAtFrom: "#{from_date.to_datetime.rfc3339}",
+                createdAtTo: "#{to_date.to_datetime.rfc3339}",
+                branch: "#{branch}",
+              ) {
+                edges {
+                  node {
+                    url
+                    id
+                    state
+                    createdAt
+                    message
+                  }
+                }
+                pageInfo { # For build pagination
+                  hasNextPage
+                  endCursor
+                }
+              }
+            }
+          }
+        GRAPHQL
+
+        response_data = execute_graphql_query(query)
+        builds_data = response_data.dig('data', 'pipeline', 'builds')
+
+        if builds_data && builds_data['edges']
+          all_build_edges.concat(builds_data['edges'])
+          page_info = builds_data['pageInfo']
+          has_next_page = page_info['hasNextPage']
+          after_cursor = page_info['endCursor']
+        else
+          # No builds data or error in structure, stop pagination
+          has_next_page = false
+        end
+      end
+
+      all_build_edges
+    rescue StandardError => e
+      log.error(
+        "Error in get_pipeline_builds for #{org}/#{pipeline}: #{e.message}",
+      )
+      [] # Return empty array on error
+    end
+
+    private
+
+    def execute_graphql_query(query)
+      http = Net::HTTP.new(@graphql_endpoint.host, @graphql_endpoint.port)
+      http.use_ssl = true
+      request = Net::HTTP::Post.new(@graphql_endpoint.request_uri)
+      request['Authorization'] = "Bearer #{@token}"
+      request['Content-Type'] = 'application/json'
+      request.body = { query: }.to_json
+
+      begin
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          error_message = 'Buildkite API request failed with status ' \
+                          "#{response.code}: #{response.message}"
+          log.error(error_message)
+          raise error_message
+        end
+
+        parsed_response = JSON.parse(response.body)
+
+        if parsed_response['errors']
+          # Log each error for better context if multiple errors are returned
+          error_details = parsed_response['errors'].map do |e|
+            msg = e['message']
+            path = e['path'] ? " (path: #{e['path'].join(' -> ')})" : ''
+            "#{msg}#{path}"
+          end.join('; ')
+          error_message = "Buildkite API returned errors: #{error_details}"
+          log.error(error_message)
+          # Also log the full error response for detailed debugging
+          log.debug(
+            "Full Buildkite error response: #{parsed_response['errors']}",
+          )
+          raise error_message
+        end
+        parsed_response
+      rescue Net::HTTPExceptions => e
+        error_message =
+          "Network error connecting to Buildkite API: #{e.message}"
+        log.error(error_message)
+        raise error_message
+      rescue JSON::ParserError => e
+        error_message = "Error parsing JSON from Buildkite API: #{e.message}."
+        log.error(error_message)
+        log.debug("Problematic JSON response body: #{response&.body}")
+        raise error_message
+      rescue StandardError => e
+        error_message =
+          "Unexpected error during Buildkite API call: #{e.message}"
+        log.error(error_message)
+        raise error_message
+      end
+    end
+  end
+end

data/lib/oss_stats/buildkite_token.rb

@@ -0,0 +1,15 @@
+def get_buildkite_token(options)
+  return options[:buildkite_token] if options[:buildkite_tokne]
+  return ENV['BUILDKITE_API_TOKEN'] if ENV['BUILDKITE_API_TOKEN']
+  nil
+end
+
+def get_buildkite_token!(config = OssStats::CiStatsConfig)
+  token = get_buildkite_token(config)
+  unless token
+    raise ArgumentError,
+      'Buildkite token not found. Set via --buildkite-token CLI option, ' +
+      'in the conifg, or as BUILDKITE_API_TOKEN environment variable.'
+  end
+  token
+end

data/lib/oss_stats/config/meeting_stats.rb

@@ -0,0 +1,36 @@
+require 'mixlib/config'
+require_relative 'shared'
+
+module OssStats
+  module Config
+    module MeetingStats
+      extend Mixlib::Config
+      extend OssStats::Config::Shared
+
+      db_file File.expand_path('./data/meeting_data.sqlite3', Dir.pwd)
+      dryrun false
+      header <<~EOF
+        # Meeting Stats
+
+        This document tracks meeting attendance and participation.
+        It was generated by slack_meeting_stats.rb, do not edit manually.
+
+        ## Trends
+
+        [![Attendance](images/attendance-small.png)](images/attendance-full.png)
+        [![Build Status
+           Reports](images/build_status-small.png)](images/build_status-full.png)
+
+      EOF
+      output File.expand_path('./meeting_stats.md', Dir.pwd)
+      image_dir File.expand_path('./images', Dir.pwd)
+      log_level :info
+      mode 'record'
+      teams []
+
+      def self.config_file
+        find_config_file('meeting_stats_config.rb')
+      end
+    end
+  end
+end

data/lib/oss_stats/config/promise_stats.rb

@@ -0,0 +1,22 @@
+require 'mixlib/config'
+require_relative 'shared'
+
+module OssStats
+  module Config
+    module Promises
+      extend Mixlib::Config
+      extend OssStats::Config::Shared
+
+      db_file File.expand_path('./data/promises.sqlite3', Dir.pwd)
+      dryrun false
+      output nil
+      log_level :info
+      mode 'status'
+      include_abandoned false
+
+      def self.config_file
+        find_config_file('promises_config.rb')
+      end
+    end
+  end
+end

data/lib/oss_stats/config/repo_stats.rb

@@ -0,0 +1,47 @@
+require 'mixlib/config'
+require_relative 'shared'
+
+module OssStats
+  module Config
+    module RepoStats
+      extend Mixlib::Config
+      extend OssStats::Config::Shared
+
+      # generally these should NOT be set, they override everything
+      days nil
+      branches nil
+      top_n_stale nil
+      top_n_oldest nil
+      top_n_time_to_close nil
+      top_n_most_broken_ci_days nil
+      top_n_most_broken_ci_jobs nil
+      top_n_stale_pr nil
+      top_n_stale_issue nil
+      top_n_oldest_pr nil
+      top_n_oldest_issue nil
+      top_n_time_to_close_pr nil
+      top_n_time_to_close_issue nil
+
+      # set these instead
+      default_branches ['main']
+      default_days 30
+
+      log_level :info
+      ci_timeout 600
+      no_links false
+      github_api_endpoint nil
+      github_token nil
+      github_org nil
+      github_repo nil
+      buildkite_token nil
+      limit_gh_ops_per_minute nil
+      include_list false
+      mode ['all']
+      organizations({})
+
+      def self.config_file
+        find_config_file('repo_stats_config.rb')
+      end
+    end
+  end
+end

data/lib/oss_stats/config/shared.rb

@@ -0,0 +1,43 @@
+require_relative '../log'
+
+module OssStats
+  module Config
+    module Shared
+      # a common method among all config parsers to
+      # find the config file
+      def find_config_file(filename)
+        log.debug("#{name}: config_file called")
+
+        # Check to see if `config` has been defined
+        # in the current config, and if so, return that.
+        #
+        # Slight magic here, name will be, for example
+        #   OssStats::Config::RepoStats
+        # So we trip the first part and get just `RepoStats`,
+        # then get the class, and check for config, akin to doing
+        #
+        #   if OssStats::Config::RepoStats.config
+        #     return OssStats::Config::RepoStats.config
+        #   end
+        kls = name.sub('OssStats::Config::', '')
+        config_class = OssStats::Config.const_get(kls)
+        if config_class.config
+          return config_class.config
+        end
+
+        # otherwise, we check CWD, XDG, and /etc.
+        [
+          Dir.pwd,
+          File.join(ENV['HOME'], '.config', 'oss_stats'),
+          '/etc',
+        ].each do |dir|
+          f = File.join(dir, filename)
+          log.debug("[#{name}] Checking if #{f} exists...")
+          return f if ::File.exist?(f)
+        end
+
+        nil
+      end
+    end
+  end
+end