kusameter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28ba868a9d5bf6bc11810650cb371bfaa57b459159ab30992efca1fc45d3bdae
+  data.tar.gz: fdb47839bd5232b2d76ecc8cbdd1872d2f3773eed8f7ae6f2fd0d24c33c06d8d
+SHA512:
+  metadata.gz: 5382af9708f4a1cb383366133a108ac05c2dae0a8a961f8455b035adadf477b679dc9fba2e4a03a4407d8062d0d478b9efa18434fe023e731cf8ff94e3e2253f
+  data.tar.gz: 6ce4568b40dedfec2f287ae1585acf323830ce2e760f42a55e3b7c8b8c6b441bed4a546bdd414e61371b68212a167768d81b5d0dcc541f8d8fa869c04b5fee6c

data/.rubocop.yml

@@ -0,0 +1,3 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-06
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# Kusameter
+
+Kusameter measures a GitHub user's contributions to public repositories over a date range. It counts pull requests, commits, issues, and pull request reviews through a Ruby API or a CLI.
+
+Ruby 3.3 or later is required. The gem has no runtime dependencies outside Ruby's standard library.
+
+## Install
+
+Add `gem "kusameter"` to your Gemfile, or run `gem install kusameter` after the gem has been published. From a checkout, run `bundle install` and use `bundle exec exe/kusameter`.
+
+Set a GitHub token with access to public repositories. `KUSAMETER_TOKEN` takes precedence over `GITHUB_TOKEN`; a token set through `Kusameter.configure` takes precedence over both. The CLI accepts tokens only through the environment.
+
+```sh
+export KUSAMETER_TOKEN=your_token
+bundle exec exe/kusameter octocat --year 2025
+```
+
+## CLI
+
+```sh
+kusameter octocat
+kusameter octocat --from 2023-04-01 --to 2026-03-31 --exclude-own
+kusameter octocat --year 2025 --exclude-forks --by-repo
+kusameter octocat --year 2025 --period 1Q
+kusameter octocat --year 2025 --period H1
+kusameter alice bob --year 2025 --format csv > contributions.csv
+kusameter octocat --source search --merged-only --format json
+```
+
+Without dates, the CLI covers the last year through today. `--year YYYY` selects a calendar year. Add `--period` to select a quarter or half-year within that year; without `--year`, it uses the current year. Periods use calendar boundaries: `1Q` is January–March and `H1` is January–June. `--year` and `--period` cannot be combined with `--from` or `--to`. Future end dates are capped at today.
+
+| Option | Meaning |
+| --- | --- |
+| `--from DATE`, `--to DATE` | Inclusive ISO 8601 dates |
+| `--year YYYY` | Calendar year |
+| `--period NAME` | `1Q`–`4Q`, `H1`/`H2`, or the aliases `上期`/`下期` |
+| `--source graphql\|search` | Data source; GraphQL is the default |
+| `--exclude-own`, `--exclude-forks` | Exclude repositories owned by the user or forks |
+| `--exclude-org NAME`, `--include-org NAME` | Exclude or include repository owners; repeatable |
+| `--merged-only` | Count only merged PRs; requires Search |
+| `--by-repo` | Include a repository breakdown in table or JSON output |
+| `--format table\|json\|csv` | Output format; table is the default |
+| `--time-zone TZ` | Date boundary zone, such as `UTC`, `Asia/Tokyo`, or `+09:00` |
+| `-h`, `--help`; `-v`, `--version` | Help or version |
+
+Exit codes are 0 for success, 1 for an API or other error, 2 for invalid input, 3 for missing credentials or authentication failure, 4 for a rate limit, and 5 for a missing user. With multiple users, successful results are still printed if another user fails; the exit code reflects the first failure.
+
+## Ruby API
+
+```ruby
+require "kusameter"
+
+result = Kusameter.stats("octocat", from: "2025-01-01", to: "2025-12-31", exclude_own: true)
+puts result.pull_requests
+puts result.commits
+puts result.issues
+puts result.reviews
+puts result.total
+result.by_repository.each { |repo| puts "#{repo.name_with_owner}: #{repo.commits} commits" }
+puts result.warnings if result.truncated?
+
+results = Kusameter.stats_for(%w[alice bob], from: "2025-01-01", to: "2025-12-31")
+```
+
+`Kusameter.stats` accepts `Date`, `Time`, or ISO 8601 date strings for `from` and `to`. Its result exposes the four counts, `period`, `source`, `by_repository`, `warnings`, `total`, `truncated?`, and `to_h`.
+
+```ruby
+Kusameter.configure do |config|
+  config.token = ENV.fetch("MY_GITHUB_TOKEN")
+  config.source = :graphql
+  config.time_zone = "Asia/Tokyo"
+  config.timeout = 30
+  config.max_retries = 3
+  config.max_rate_limit_wait = 60
+end
+```
+
+For GitHub Enterprise Server, also set `api_endpoint` to `https://HOST/api/v3` and `graphql_endpoint` to `https://HOST/api/graphql`.
+
+## Counting rules and limits
+
+GraphQL is the default source. It follows [GitHub's contribution rules](https://docs.github.com/en/account-and-profile/reference/profile-contributions-reference) and counts only public repositories. A commit must be linked to the user and present on the default branch or `gh-pages` to count. Commits that exist only on a fork do not count. GraphQL review contributions reflect [GitHub's contribution collection](https://docs.github.com/en/graphql/reference/users), which represents the latest submitted review per reviewed PR. A range longer than one year is divided into one-year requests and summed.
+
+GraphQL returns at most 100 repositories per metric and request. When a response reaches that limit and its repository counts fall short of the collection totals, Kusameter splits the date range and retries each half. It continues until the counts are complete or the range is a single day. Any remaining difference produces a warning; filtered counts always come from the returned repositories, and `truncated?` reports that warning.
+
+The optional Search source counts PRs, issues, and commits with GitHub Search. Its review metric counts reviewed PRs by PR creation date, so it is an approximation of reviews submitted during the requested period. Search does not provide a repository breakdown and cannot exclude forks; it warns when `exclude_forks` is requested or GitHub reports incomplete results. `merged_only` applies only to the PR metric. Search requests are spaced by at least two seconds to respect its tighter rate limit. Date boundaries for Search use GitHub's date query syntax; `time_zone` controls GraphQL boundaries and the default end date.
+
+API rate limits are retried up to `max_retries` when the required wait does not exceed `max_rate_limit_wait`. Otherwise `Kusameter::RateLimitError` provides `reset_at`. Authentication, missing users, invalid periods, and other API failures raise subclasses of `Kusameter::Error`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rubocop --only Lint
+bundle exec rbs validate
+bundle exec steep check
+```
+
+Tests use fake HTTP responses and do not call GitHub. `bundle exec rake` enforces at least 90% line coverage and checks the public API facade with Steep. The project is licensed under [MIT](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+ENV["KUSAMETER_COVERAGE"] = "1"
+RSpec::Core::RakeTask.new(:spec)
+
+task :lint do
+  sh "bundle exec rubocop --only Lint"
+  sh "bundle exec rbs validate"
+  sh "bundle exec steep check"
+end
+
+task default: %i[spec lint]

data/Steepfile

@@ -0,0 +1,5 @@
+target :public_api do
+  library "date"
+  signature "sig"
+  check "lib/kusameter.rb"
+end

data/exe/kusameter

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "kusameter"
+
+exit Kusameter::CLI.new.run(ARGV)

data/lib/kusameter/calculator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kusameter
+  class Calculator
+    def initialize(source:)
+      @source = source
+    end
+
+    def call(login:, period:, filter:)
+      windows = @source.max_period ? period.split : [period]
+      windows.map { |window| @source.fetch(login:, period: window, filter:) }
+             .reduce(:merge).with(period:)
+    end
+  end
+end

data/lib/kusameter/cli.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Kusameter
+  class CLI
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(args)
+      options = { exclude_orgs: [], include_orgs: [] }
+      format = "table"
+      by_repo = false
+      year = nil
+      period = nil
+      zone = nil
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: kusameter [options] LOGIN [LOGIN ...]"
+        opts.on("--from DATE", "Start date") { |value| options[:from] = value }
+        opts.on("--to DATE", "End date") { |value| options[:to] = value }
+        opts.on("--year YYYY", "Calendar year") { |value| year = value }
+        opts.on("--period NAME", "1Q, 2Q, 3Q, 4Q, H1, or H2") { |value| period = value }
+        opts.on("--source NAME", "graphql or search") { |value| options[:source] = value.to_sym }
+        opts.on("--exclude-own", "Exclude repositories owned by the user") { options[:exclude_own] = true }
+        opts.on("--exclude-forks", "Exclude forks") { options[:exclude_forks] = true }
+        opts.on("--exclude-org NAME", "Exclude an owner") { |value| options[:exclude_orgs] << value }
+        opts.on("--include-org NAME", "Include an owner") { |value| options[:include_orgs] << value }
+        opts.on("--merged-only", "Count merged PRs (search only)") { options[:merged_only] = true }
+        opts.on("--by-repo", "Show repository breakdown") { by_repo = true }
+        opts.on("--format NAME", "table, json, or csv") { |value| format = value }
+        opts.on("--time-zone TZ", "Date boundary time zone") { |value| zone = value }
+        opts.on("-v", "--version", "Show version") { @stdout.puts(VERSION); return 0 }
+        opts.on("-h", "--help", "Show help") { @stdout.puts(opts); return 0 }
+      end
+      logins = parser.parse(args.dup)
+      raise ArgumentError, "at least one LOGIN is required" if logins.empty?
+      raise ArgumentError, "--year cannot be combined with --from or --to" if year && (options[:from] || options[:to])
+      raise ArgumentError, "--period cannot be combined with --from or --to" if period && (options[:from] || options[:to])
+      raise ArgumentError, "invalid year" if year && !year.match?(/\A\d{4}\z/)
+      raise ArgumentError, "invalid format" unless %w[table json csv].include?(format)
+      raise ArgumentError, "invalid source" if options[:source] && !%i[graphql search].include?(options[:source])
+      raise ArgumentError, "--merged-only requires --source search" if options[:merged_only] && (options[:source] || configuration.source) != :search
+
+      if zone
+        original_zone = configuration.time_zone
+        configuration.time_zone = zone
+        begin
+          configuration.today
+        rescue ConfigurationError => error
+          raise ArgumentError, error.message
+        end
+      end
+      if period
+        ranges = { "1Q" => [0, 3], "2Q" => [3, 3], "3Q" => [6, 3], "4Q" => [9, 3],
+                   "H1" => [0, 6], "H2" => [6, 6], "上期" => [0, 6], "下期" => [6, 6] }
+        offset, months = ranges[period.upcase]
+        raise ArgumentError, "invalid period" unless offset
+
+        start_date = Date.new(year ? year.to_i : configuration.today.year, 1, 1) >> offset
+        options[:from] = start_date
+        options[:to] = (start_date >> months) - 1
+      elsif year
+        options[:from] = Date.new(year.to_i, 1, 1)
+        options[:to] = Date.new(year.to_i, 12, 31)
+      end
+      results = []
+      exit_code = 0
+      logins.each do |login|
+        results << Kusameter.stats(login, **options)
+      rescue Error, ArgumentError => error
+        exit_code = error_code(error) if exit_code.zero?
+        @stderr.puts(redact("#{login}: #{error.message}"))
+      end
+      unless results.empty?
+        formatter = { "table" => Formatters::Table, "json" => Formatters::Json, "csv" => Formatters::Csv }.fetch(format)
+        @stdout.print(formatter.new.call(results, by_repo:))
+        results.each { |result| result.warnings.each { |warning| @stderr.puts("#{result.login}: #{warning}") } } unless format == "json"
+      end
+      exit_code
+    rescue OptionParser::ParseError, ArgumentError, InvalidPeriodError => error
+      @stderr.puts(redact(error.message))
+      2
+    rescue ConfigurationError, AuthenticationError => error
+      @stderr.puts(redact(error.message))
+      3
+    ensure
+      configuration.time_zone = original_zone if original_zone
+    end
+
+    private
+
+    def configuration = Kusameter.configuration
+
+    def redact(message)
+      secret = configuration.token || ENV["KUSAMETER_TOKEN"] || ENV["GITHUB_TOKEN"]
+      secret && !secret.empty? ? message.gsub(secret, "[FILTERED]") : message
+    end
+
+    def error_code(error)
+      case error
+      when InvalidPeriodError, ArgumentError then 2
+      when ConfigurationError, AuthenticationError then 3
+      when RateLimitError then 4
+      when UserNotFoundError then 5
+      else 1
+      end
+    end
+  end
+end

data/lib/kusameter/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Kusameter
+  class Configuration
+    ZONE_MUTEX = Mutex.new
+    attr_accessor :token, :api_endpoint, :graphql_endpoint, :source, :time_zone,
+                  :timeout, :max_retries, :max_rate_limit_wait, :logger
+
+    def initialize
+      @token = nil
+      @api_endpoint = "https://api.github.com"
+      @graphql_endpoint = "https://api.github.com/graphql"
+      @source = :graphql
+      @time_zone = "UTC"
+      @timeout = 30
+      @max_retries = 3
+      @max_rate_limit_wait = 60
+      @logger = nil
+    end
+
+    def resolved_token
+      value = token || ENV["KUSAMETER_TOKEN"] || ENV["GITHUB_TOKEN"]
+      raise ConfigurationError, "GitHub token is required" if value.nil? || value.empty?
+
+      value
+    end
+
+    def inspect
+      description = "#<#{self.class} token=[FILTERED] api_endpoint=#{api_endpoint.inspect} " \
+                    "graphql_endpoint=#{graphql_endpoint.inspect} source=#{source.inspect} time_zone=#{time_zone.inspect}>"
+      secret = token || ENV["KUSAMETER_TOKEN"] || ENV["GITHUB_TOKEN"]
+      secret && !secret.empty? ? description.gsub(secret, "[FILTERED]") : description
+    end
+
+    def today = in_time_zone { |offset| offset ? Time.now.getlocal(offset).to_date : Time.now.to_date }
+
+    def start_of(date)
+      in_time_zone { |offset| local_midnight(date, offset).iso8601 }
+    end
+
+    def end_of(date)
+      following = date + 1
+      in_time_zone { |offset| (local_midnight(following, offset) - Rational(1, 1_000_000)).iso8601(6) }
+    end
+
+    private
+
+    def local_midnight(date, offset)
+      offset ? Time.new(date.year, date.month, date.day, 0, 0, 0, offset) : Time.local(date.year, date.month, date.day)
+    end
+
+    def in_time_zone
+      zone = time_zone.to_s
+      offset = zone.match?(/\A[+-](?:0\d|1[0-4]):[0-5]\d\z/)
+      valid = zone == "UTC" || offset ||
+              (zone.match?(/\A[A-Za-z_]+(?:\/[A-Za-z_]+)+\z/) && File.file?("/usr/share/zoneinfo/#{zone}"))
+      raise ConfigurationError, "invalid time zone" unless valid
+      return yield zone if offset
+
+      # ponytail: TZ is process-wide; use a timezone library if concurrent calls need different zones.
+      ZONE_MUTEX.synchronize do
+        previous = ENV["TZ"]
+        ENV["TZ"] = zone
+        begin
+          yield
+        ensure
+          previous ? ENV["TZ"] = previous : ENV.delete("TZ")
+        end
+      end
+    end
+  end
+end

data/lib/kusameter/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kusameter
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class InvalidPeriodError < Error; end
+  class AuthenticationError < Error; end
+  class UserNotFoundError < Error; end
+
+  class RateLimitError < Error
+    attr_reader :reset_at
+
+    def initialize(message = "GitHub API rate limit exceeded", reset_at: nil)
+      @reset_at = reset_at
+      super(message)
+    end
+  end
+
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message = "GitHub API error", status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+end

data/lib/kusameter/filter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kusameter
+  Filter = Data.define(:exclude_own, :exclude_forks, :exclude_orgs, :include_orgs, :merged_only) do
+    def initialize(exclude_own: false, exclude_forks: false, exclude_orgs: [], include_orgs: [], merged_only: false)
+      excluded = Array(exclude_orgs)
+      included = Array(include_orgs)
+      names = excluded + included
+      raise ArgumentError, "invalid repository owner" unless names.all? { |name| name.is_a?(String) && name.match?(/\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\z/) }
+
+      super(exclude_own:, exclude_forks:, exclude_orgs: excluded, include_orgs: included, merged_only:)
+    end
+
+    def match?(repo, login:)
+      owner = repo.fetch("owner").fetch("login")
+      return false if repo.fetch("isPrivate")
+      return false if exclude_own && owner.casecmp?(login)
+      return false if exclude_forks && repo.fetch("isFork")
+      return false if exclude_orgs.any? { |name| owner.casecmp?(name) }
+      return false if include_orgs.any? && include_orgs.none? { |name| owner.casecmp?(name) }
+
+      true
+    end
+  end
+end

data/lib/kusameter/formatters/csv.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kusameter
+  module Formatters
+    class Csv
+      HEADER = %w[login from to pull_requests commits issues reviews].freeze
+
+      def call(results, **_options)
+        rows = results.map do |result|
+          [result.login, result.period.from, result.period.to, result.pull_requests,
+           result.commits, result.issues, result.reviews]
+        end
+        ([HEADER] + rows).map { |row| row.join(",") }.join("\n") + "\n"
+      end
+    end
+  end
+end

data/lib/kusameter/formatters/json.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kusameter
+  module Formatters
+    class Json
+      def call(results, by_repo: false)
+        values = results.map do |result|
+          hash = result.to_h
+          hash.delete(:by_repository) unless by_repo
+          hash
+        end
+        JSON.pretty_generate(values.length == 1 ? values.first : values) + "\n"
+      end
+    end
+  end
+end

data/lib/kusameter/formatters/table.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kusameter
+  module Formatters
+    class Table
+      def call(results, by_repo: false)
+        rows = results.map do |result|
+          [result.login, "#{result.period.from}..#{result.period.to}", result.pull_requests,
+           result.commits, result.issues, result.reviews].map(&:to_s)
+        end
+        lines = render(%w[LOGIN PERIOD PRS COMMITS ISSUES REVIEWS], rows)
+        if by_repo
+          results.each do |result|
+            next if result.by_repository.empty?
+
+            detail = result.by_repository.map do |repo|
+              [repo.name_with_owner, repo.pull_requests, repo.commits, repo.issues, repo.reviews].map(&:to_s)
+            end
+            lines << "\n#{result.login} repositories:"
+            lines.concat(render(%w[REPOSITORY PRS COMMITS ISSUES REVIEWS], detail))
+          end
+        end
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def render(header, rows)
+        widths = header.each_index.map { |index| ([header[index]] + rows.map { |row| row[index] }).map(&:length).max }
+        ([header] + rows).map do |row|
+          row.each_with_index.map { |value, index| value.ljust(widths[index]) }.join("  ").rstrip
+        end
+      end
+    end
+  end
+end

data/lib/kusameter/http/client.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Kusameter
+  module HTTP
+    class Client
+      TRANSIENT = [502, 503, 504].freeze
+      NETWORK_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED].freeze
+
+      def initialize(configuration, transport: nil, sleeper: Kernel.method(:sleep))
+        @configuration = configuration
+        @transport = transport || method(:default_transport)
+        @sleeper = sleeper
+      end
+
+      def graphql(query, variables)
+        uri = endpoint(@configuration.graphql_endpoint)
+        request = Net::HTTP::Post.new(uri.request_uri, headers)
+        request.body = JSON.generate(query:, variables:)
+        parse(perform(uri, request), graphql: true)
+      end
+
+      def get(path, params = {})
+        base = @configuration.api_endpoint.chomp("/")
+        uri = endpoint("#{base}#{path}")
+        uri.query = URI.encode_www_form(params)
+        parse(perform(uri, Net::HTTP::Get.new(uri.request_uri, headers)))
+      end
+
+      private
+
+      def endpoint(value)
+        uri = URI.parse(value)
+        raise ConfigurationError, "API endpoint must use HTTPS" unless uri.is_a?(URI::HTTPS) && uri.host && !uri.userinfo
+
+        uri
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "invalid API endpoint"
+      end
+
+      def headers
+        { "Authorization" => "Bearer #{@configuration.resolved_token}",
+          "User-Agent" => "kusameter/#{VERSION}",
+          "Accept" => "application/vnd.github+json",
+          "Content-Type" => "application/json" }
+      end
+
+      def default_transport(uri, request)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: @configuration.timeout,
+                        read_timeout: @configuration.timeout) { |http| http.request(request) }
+      end
+
+      def perform(uri, request)
+        retries = 0
+        loop do
+          response = @transport.call(uri, request)
+          status = response.code.to_i
+          if rate_limited?(response)
+            reset_at, wait = rate_wait(response)
+            raise RateLimitError.new(reset_at:) if wait > @configuration.max_rate_limit_wait || retries >= @configuration.max_retries
+
+            @sleeper.call(wait)
+          elsif TRANSIENT.include?(status)
+            raise APIError.new("GitHub API unavailable", status:) if retries >= @configuration.max_retries
+
+            @sleeper.call(2**retries)
+          else
+            return response
+          end
+          retries += 1
+        rescue *NETWORK_ERRORS
+          raise APIError, "GitHub API connection failed" if retries >= @configuration.max_retries
+
+          @sleeper.call(2**retries)
+          retries += 1
+        end
+      end
+
+      def rate_limited?(response)
+        [403, 429].include?(response.code.to_i) &&
+          (response.code.to_i == 429 || response["x-ratelimit-remaining"] == "0" || response["retry-after"])
+      end
+
+      def rate_wait(response)
+        if response["retry-after"]
+          wait = [response["retry-after"].to_f, 0].max
+          [Time.now + wait, wait]
+        elsif response["x-ratelimit-reset"]
+          reset_at = Time.at(response["x-ratelimit-reset"].to_i)
+          [reset_at, [reset_at - Time.now, 0].max]
+        else
+          [Time.now, 0]
+        end
+      end
+
+      def parse(response, graphql: false)
+        status = response.code.to_i
+        raise AuthenticationError, "GitHub authentication failed" if status == 401
+        raise APIError.new("GitHub API returned HTTP #{status}", status:, body: safe_body(response.body)) unless status.between?(200, 299)
+
+        data = JSON.parse(response.body)
+        return data unless graphql && data["errors"]&.any?
+
+        raise UserNotFoundError, "GitHub user not found" if data["errors"].any? { |error| error["type"] == "NOT_FOUND" }
+
+        raise APIError, "GitHub GraphQL request failed"
+      rescue JSON::ParserError
+        raise APIError.new("Invalid GitHub API response", status:)
+      end
+
+      def safe_body(body)
+        body.to_s.gsub(@configuration.resolved_token, "[FILTERED]")
+      end
+    end
+  end
+end

data/lib/kusameter/period.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Kusameter
+  Period = Data.define(:from, :to) do
+    def initialize(from:, to:)
+      from = parse_date(from)
+      to = parse_date(to)
+      raise InvalidPeriodError, "from must be on or before to" if from > to
+
+      super
+    end
+
+    def split
+      windows = []
+      cursor = from
+      while cursor <= to
+        finish = [cursor.next_year - 1, to].min
+        windows << self.class.new(from: cursor, to: finish)
+        cursor = finish + 1
+      end
+      windows
+    end
+
+    private
+
+    def parse_date(value)
+      case value
+      when Date then value
+      when Time then value.to_date
+      when String then Date.iso8601(value)
+      else raise InvalidPeriodError, "date must be a Date, Time, or ISO 8601 string"
+      end
+    rescue Date::Error
+      raise InvalidPeriodError, "invalid ISO 8601 date"
+    end
+  end
+end

data/lib/kusameter/result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kusameter
+  RepositoryStat = Data.define(:name_with_owner, :pull_requests, :commits, :issues, :reviews) do
+    def to_h = { name_with_owner:, pull_requests:, commits:, issues:, reviews: }
+  end
+
+  Result = Data.define(:login, :period, :source, :pull_requests, :commits, :issues, :reviews, :by_repository, :warnings) do
+    def merge(other)
+      raise ArgumentError, "cannot merge different users or sources" unless login == other.login && source == other.source
+
+      repos = (by_repository + other.by_repository).group_by { |repo| repo.name_with_owner.downcase }.values.map do |items|
+        RepositoryStat.new(name_with_owner: items.first.name_with_owner,
+                           **count_keys.to_h { |key| [key, items.sum(&key)] })
+      end
+      self.class.new(login:, source:, period: Period.new(from: [period.from, other.period.from].min,
+                                                         to: [period.to, other.period.to].max),
+                     **count_keys.to_h { |key| [key, public_send(key) + other.public_send(key)] },
+                     by_repository: repos.sort_by(&:name_with_owner), warnings: (warnings + other.warnings).uniq)
+    end
+
+    def total = count_keys.sum { |key| public_send(key) }
+    def truncated? = warnings.any? { |warning| warning.start_with?("Truncated") }
+
+    def to_h
+      { login:, period: { from: period.from.iso8601, to: period.to.iso8601 }, source:,
+        **count_keys.to_h { |key| [key, public_send(key)] },
+        by_repository: by_repository.map(&:to_h), warnings: }
+    end
+
+    private
+
+    def count_keys = %i[pull_requests commits issues reviews]
+  end
+end

data/lib/kusameter/sources/graphql/query.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kusameter
+  module Sources
+    class GraphQL
+      QUERY = <<~GRAPHQL.freeze
+        query($login: String!, $from: DateTime!, $to: DateTime!) {
+          user(login: $login) {
+            contributionsCollection(from: $from, to: $to) {
+              totalCommitContributions
+              totalIssueContributions
+              totalPullRequestContributions
+              totalPullRequestReviewContributions
+              commitContributionsByRepository(maxRepositories: 100) {
+                repository { ...Repo }
+                contributions { totalCount }
+              }
+              issueContributionsByRepository(maxRepositories: 100) {
+                repository { ...Repo }
+                contributions { totalCount }
+              }
+              pullRequestContributionsByRepository(maxRepositories: 100) {
+                repository { ...Repo }
+                contributions { totalCount }
+              }
+              pullRequestReviewContributionsByRepository(maxRepositories: 100) {
+                repository { ...Repo }
+                contributions { totalCount }
+              }
+            }
+          }
+        }
+        fragment Repo on Repository {
+          nameWithOwner
+          isPrivate
+          isFork
+          owner { login }
+        }
+      GRAPHQL
+    end
+  end
+end

data/lib/kusameter/sources/graphql.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Kusameter
+  module Sources
+    class GraphQL
+      FIELDS = {
+        pull_requests: %w[pullRequestContributionsByRepository totalPullRequestContributions],
+        commits: %w[commitContributionsByRepository totalCommitContributions],
+        issues: %w[issueContributionsByRepository totalIssueContributions],
+        reviews: %w[pullRequestReviewContributionsByRepository totalPullRequestReviewContributions]
+      }.freeze
+
+      def initialize(client:, configuration:)
+        @client = client
+        @configuration = configuration
+      end
+
+      def max_period = :year
+
+      def fetch(login:, period:, filter:)
+        variables = { login:, from: @configuration.start_of(period.from), to: @configuration.end_of(period.to) }
+        response = @client.graphql(QUERY, variables)
+        errors = response["errors"] || []
+        raise UserNotFoundError, "GitHub user not found" if errors.any? { |error| error["type"] == "NOT_FOUND" }
+        raise APIError, "GitHub GraphQL request failed" if errors.any?
+
+        user = response.dig("data", "user")
+        raise UserNotFoundError, "GitHub user not found" unless user
+
+        collection = user.fetch("contributionsCollection")
+        counts = {}
+        repositories = {}
+        warnings = []
+        limited = false
+        FIELDS.each do |metric, (field, total_field)|
+          entries = collection.fetch(field)
+          visible = entries.sum { |entry| entry.dig("contributions", "totalCount") }
+          if visible < collection.fetch(total_field)
+            at_limit = entries.length == 100
+            reason = at_limit ? "100 repository limit" : "repository totals differ"
+            warnings << "Truncated #{metric} contributions (#{reason})"
+            limited ||= at_limit
+          end
+          counts[metric] = 0
+          entries.each do |entry|
+            repo = entry.fetch("repository")
+            next unless filter.match?(repo, login:)
+
+            count = entry.dig("contributions", "totalCount")
+            counts[metric] += count
+            name = repo.fetch("nameWithOwner")
+            repositories[name] ||= { pull_requests: 0, commits: 0, issues: 0, reviews: 0 }
+            repositories[name][metric] += count
+          end
+        end
+
+        breakdown = repositories.map { |name, values| RepositoryStat.new(name_with_owner: name, **values) }
+        result = Result.new(login:, period:, source: :graphql, **counts,
+                            by_repository: breakdown.sort_by(&:name_with_owner), warnings:)
+        return result unless limited && period.from < period.to
+
+        middle = period.from + ((period.to - period.from).to_i / 2)
+        first = Period.new(from: period.from, to: middle)
+        second = Period.new(from: middle + 1, to: period.to)
+        fetch(login:, period: first, filter:).merge(fetch(login:, period: second, filter:))
+      end
+    end
+  end
+end
+
+require_relative "graphql/query"

data/lib/kusameter/sources/search/query_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kusameter
+  module Sources
+    class Search
+      class QueryBuilder
+        def build(metric:, login:, period:, filter:, owner: nil, owner_type: nil)
+          names = [login, owner, *filter.exclude_orgs].compact
+          raise ArgumentError, "invalid GitHub login or owner" unless names.all? { |name| name.match?(/\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\z/) }
+
+          range = "#{period.from.iso8601}..#{period.to.iso8601}"
+          terms = case metric
+                  when :pull_requests then ["type:pr", "author:#{login}", "created:#{range}"]
+                  when :issues then ["type:issue", "author:#{login}", "created:#{range}"]
+                  when :reviews then ["type:pr", "reviewed-by:#{login}", "-author:#{login}", "created:#{range}"]
+                  when :commits then ["author:#{login}", "author-date:#{range}"]
+                  else raise ArgumentError, "unknown metric"
+                  end
+          terms << "is:public"
+          terms << "is:merged" if metric == :pull_requests && filter.merged_only
+          terms << "-user:#{login}" if filter.exclude_own
+          filter.exclude_orgs.each do |name|
+            terms.concat(["-org:#{name}", "-user:#{name}"])
+          end
+          terms << "#{owner_type == "Organization" ? "org" : "user"}:#{owner}" if owner
+          terms.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/kusameter/sources/search.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Kusameter
+  module Sources
+    class Search
+      PATHS = { pull_requests: "/search/issues", issues: "/search/issues",
+                reviews: "/search/issues", commits: "/search/commits" }.freeze
+
+      def initialize(client:, interval: 2, sleeper: Kernel.method(:sleep))
+        @client = client
+        @interval = interval
+        @sleeper = sleeper
+        @query_builder = QueryBuilder.new
+      end
+
+      def max_period = nil
+
+      def fetch(login:, period:, filter:)
+        owners = if filter.include_orgs.empty?
+                   [[nil, nil]]
+                 else
+                   filter.include_orgs.uniq { |name| name.downcase }.map do |name|
+                     [name, @client.get("/users/#{name}").fetch("type")]
+                   end
+                 end
+        counts = {}
+        warnings = ["Search reviews count reviewed PRs by PR creation date, not submitted reviews"]
+        warnings << "Search cannot exclude forks; exclude_forks was ignored" if filter.exclude_forks
+        requested = false
+        PATHS.each do |metric, path|
+          counts[metric] = 0
+          owners.each do |owner, owner_type|
+            @sleeper.call(@interval) if requested && @interval.positive?
+            query = @query_builder.build(metric:, login:, period:, filter:, owner:, owner_type:)
+            response = @client.get(path, q: query, per_page: 1)
+            requested = true
+            counts[metric] += response.fetch("total_count")
+            warnings << "Search results may be incomplete" if response["incomplete_results"]
+          end
+        end
+        Result.new(login:, period:, source: :search, **counts, by_repository: [], warnings: warnings.uniq)
+      end
+    end
+  end
+end
+
+require_relative "search/query_builder"

data/lib/kusameter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kusameter
+  VERSION = "0.1.0"
+end

data/lib/kusameter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "kusameter/version"
+require_relative "kusameter/errors"
+require_relative "kusameter/period"
+require_relative "kusameter/filter"
+require_relative "kusameter/result"
+require_relative "kusameter/configuration"
+require_relative "kusameter/calculator"
+require_relative "kusameter/http/client"
+require_relative "kusameter/sources/graphql"
+require_relative "kusameter/sources/search"
+require_relative "kusameter/formatters/table"
+require_relative "kusameter/formatters/json"
+require_relative "kusameter/formatters/csv"
+require_relative "kusameter/cli"
+
+module Kusameter
+  def self.configuration = (@configuration ||= Configuration.new)
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.stats(login, from: nil, to: nil, source: nil, **filter_options)
+    raise ArgumentError, "invalid GitHub login" unless login.is_a?(String) && login.match?(/\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\z/)
+
+    source ||= configuration.source
+    raise ConfigurationError, "source must be graphql or search" unless %i[graphql search].include?(source)
+
+    filter = Filter.new(**filter_options)
+    raise ConfigurationError, "merged_only requires the search source" if filter.merged_only && source == :graphql
+
+    today = configuration.today
+    finish = to ? Period.new(from: to, to: to).to : today
+    finish = [finish, today].min
+    start = from || (finish.prev_year + 1)
+    period = Period.new(from: start, to: finish)
+    client = HTTP::Client.new(configuration)
+    adapter = source == :graphql ? Sources::GraphQL.new(client:, configuration:) : Sources::Search.new(client:)
+    Calculator.new(source: adapter).call(login:, period:, filter:)
+  end
+
+  def self.stats_for(logins, **options)
+    logins.map { |login| stats(login, **options) }
+  end
+end

data/sig/internal.rbs

@@ -0,0 +1,22 @@
+module Kusameter
+  class Calculator
+    def initialize: (source: Sources::GraphQL | Sources::Search) -> void
+    def call: (login: String, period: Period, filter: Filter) -> Result
+  end
+
+  module HTTP
+    class Client
+      def initialize: (Configuration) -> void
+    end
+  end
+
+  module Sources
+    class GraphQL
+      def initialize: (client: HTTP::Client, configuration: Configuration) -> void
+    end
+
+    class Search
+      def initialize: (client: HTTP::Client) -> void
+    end
+  end
+end

data/sig/kusameter.rbs

@@ -0,0 +1,103 @@
+module Kusameter
+  VERSION: String
+
+  type date_input = Date | Time | String
+  type source = :graphql | :search
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.stats: (String login, ?from: date_input?, ?to: date_input?, ?source: source?,
+                   ?exclude_own: bool, ?exclude_forks: bool, ?exclude_orgs: Array[String],
+                   ?include_orgs: Array[String], ?merged_only: bool) -> Result
+  def self.stats_for: (Array[String] logins, **untyped options) -> Array[Result]
+
+  class Error < StandardError
+  end
+  class ConfigurationError < Error
+  end
+  class InvalidPeriodError < Error
+  end
+  class AuthenticationError < Error
+  end
+  class UserNotFoundError < Error
+  end
+  class RateLimitError < Error
+    attr_reader reset_at: Time?
+    def initialize: (?String message, ?reset_at: Time?) -> void
+  end
+  class APIError < Error
+    attr_reader status: Integer?
+    attr_reader body: String?
+    def initialize: (?String message, ?status: Integer?, ?body: String?) -> void
+  end
+
+  class Configuration
+    attr_accessor token: String?
+    attr_accessor api_endpoint: String
+    attr_accessor graphql_endpoint: String
+    attr_accessor source: source
+    attr_accessor time_zone: String
+    attr_accessor timeout: Integer
+    attr_accessor max_retries: Integer
+    attr_accessor max_rate_limit_wait: Integer
+    attr_accessor logger: untyped
+    def initialize: () -> void
+    def resolved_token: () -> String
+    def today: () -> Date
+    def start_of: (Date date) -> String
+    def end_of: (Date date) -> String
+  end
+
+  class Period
+    attr_reader from: Date
+    attr_reader to: Date
+    def initialize: (from: date_input, to: date_input) -> void
+    def split: () -> Array[Period]
+    def to_h: () -> Hash[Symbol, Date]
+    def with: (**untyped changes) -> Period
+  end
+
+  class Filter
+    attr_reader exclude_own: bool
+    attr_reader exclude_forks: bool
+    attr_reader exclude_orgs: Array[String]
+    attr_reader include_orgs: Array[String]
+    attr_reader merged_only: bool
+    def initialize: (?exclude_own: bool, ?exclude_forks: bool, ?exclude_orgs: Array[String],
+                     ?include_orgs: Array[String], ?merged_only: bool) -> void
+    def match?: (Hash[String, untyped] repo, login: String) -> bool
+    def with: (**untyped changes) -> Filter
+  end
+
+  class RepositoryStat
+    attr_reader name_with_owner: String
+    attr_reader pull_requests: Integer
+    attr_reader commits: Integer
+    attr_reader issues: Integer
+    attr_reader reviews: Integer
+    def initialize: (name_with_owner: String, pull_requests: Integer, commits: Integer,
+                     issues: Integer, reviews: Integer) -> void
+    def to_h: () -> Hash[Symbol, String | Integer]
+    def with: (**untyped changes) -> RepositoryStat
+  end
+
+  class Result
+    attr_reader login: String
+    attr_reader period: Period
+    attr_reader source: source
+    attr_reader pull_requests: Integer
+    attr_reader commits: Integer
+    attr_reader issues: Integer
+    attr_reader reviews: Integer
+    attr_reader by_repository: Array[RepositoryStat]
+    attr_reader warnings: Array[String]
+    def initialize: (login: String, period: Period, source: source,
+                     pull_requests: Integer, commits: Integer, issues: Integer, reviews: Integer,
+                     by_repository: Array[RepositoryStat], warnings: Array[String]) -> void
+    def merge: (Result other) -> Result
+    def total: () -> Integer
+    def truncated?: () -> bool
+    def to_h: () -> Hash[Symbol, untyped]
+    def with: (**untyped changes) -> Result
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: kusameter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Count public pull requests, commits, issues, and reviews with a Ruby
+  API and CLI.
+email:
+- t.yudai92@gmail.com
+executables:
+- kusameter
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- Steepfile
+- exe/kusameter
+- lib/kusameter.rb
+- lib/kusameter/calculator.rb
+- lib/kusameter/cli.rb
+- lib/kusameter/configuration.rb
+- lib/kusameter/errors.rb
+- lib/kusameter/filter.rb
+- lib/kusameter/formatters/csv.rb
+- lib/kusameter/formatters/json.rb
+- lib/kusameter/formatters/table.rb
+- lib/kusameter/http/client.rb
+- lib/kusameter/period.rb
+- lib/kusameter/result.rb
+- lib/kusameter/sources/graphql.rb
+- lib/kusameter/sources/graphql/query.rb
+- lib/kusameter/sources/search.rb
+- lib/kusameter/sources/search/query_builder.rb
+- lib/kusameter/version.rb
+- sig/internal.rbs
+- sig/kusameter.rbs
+homepage: https://github.com/ydah/kusameter
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Measure GitHub open source contributions by user and date range
+test_files: []