codepulse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 632b130d91677a3c461b9352908c9f0523fc402fe534ab41c7df9859eb3f4ec8
+  data.tar.gz: b053c80b65509c185e73d1f0f2ad9e70fbae40d9dc877bf030fddf37f7cd8fc6
+SHA512:
+  metadata.gz: 1f925aca5a64dbc2b3c6aa3811a9c986c0c874482edcc80c008e0732beadfaed0ab0e72f3f51a54006f8810557f6fff63c8dc09931c28895a2a7f7c40d7a069a
+  data.tar.gz: 7839b516b6428ee42733d2474f310a90981c782bf8eed674a01ee4abdb8e56810c133dde059db595851f84712af7094ab5bc5cc13019c9f78a337f3e91c254eb

data/README.md

@@ -0,0 +1,111 @@
+# Codepulse
+
+Terminal tool to analyze GitHub pull request pickup times, merge times, and sizes using the `gh` CLI.
+
+## Installation
+
+### Prerequisites
+
+1. Ruby 3.0+
+2. Install GitHub CLI: https://cli.github.com
+3. Authenticate:
+   ```sh
+   gh auth login
+   ```
+
+### Install the gem
+
+```sh
+gem build codepulse.gemspec
+gem install codepulse-0.1.0.gem
+```
+
+## Usage
+
+```sh
+# In a git repo (auto-detects owner/repo)
+codepulse
+
+# Or specify explicitly
+codepulse owner/repo
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-s`, `--state STATE` | `open`, `closed`, or `all` | `all` |
+| `-l`, `--limit COUNT` | Max PRs to fetch | auto (5 × business-days) |
+| `--business-days DAYS` | PRs from last N business days | `7` |
+| `--details` | Show individual PR table (sorted by slowest pickup) | off |
+| `--gh-command PATH` | Custom `gh` executable path | `gh` |
+
+### Examples
+
+```sh
+# Summary for current repo (last 14 business days)
+codepulse
+
+# Summary for specific repo
+codepulse rails/rails
+
+# With individual PR details
+codepulse rails/rails --details
+
+# Last 30 business days, limit 50 PRs
+codepulse rails/rails --business-days 30 --limit 50
+```
+
+## Output
+
+```
+======================================================================================
+  PR PICKUP TIME REPORT | Last 14 business days (Dec 4 - Dec 24)
+  rails/rails
+======================================================================================
+
+--------------------------------------------------------------------------------------
+  SUMMARY (18 PRs with pickup, 5 pending)
+--------------------------------------------------------------------------------------
+
+  Average pickup time:  4h 23m
+  Median pickup time:   2h 15m
+  p95 pickup time:      1d 8h
+  Fastest pickup time:  8m
+  Slowest pickup time:  2d 5h
+
+  Average time to merge:  1d 2h
+  Median time to merge:   18h 30m
+  p95 time to merge:      3d 4h
+  Fastest time to merge:  45m
+  Slowest time to merge:  5d 12h
+
+  ...
+```
+
+## What is calculated
+
+- **Pickup time**: Time from PR creation to first non-author response (business days only, Mon–Fri)
+- **Time to merge**: Time from PR creation to merge
+- **PR size**: Net lines (additions − deletions) and files changed
+- **Stats**: Average, median, p95, fastest, slowest
+
+## Filters
+
+- **Default 14 business days**: Only analyzes recent PRs
+- **Closed unmerged PRs excluded**: Abandoned PRs are filtered out
+- **Bots ignored**: Copilot, GitHub Actions, and other bot reviewers don't count as pickup
+
+## Development
+
+```sh
+# Run tests
+rake test
+
+# Lint (requires: gem install rubocop)
+rubocop
+
+# Rebuild and install
+gem build codepulse.gemspec
+gem install codepulse-0.1.0.gem
+```

data/bin/codepulse

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "codepulse"
+
+Codepulse::CLI.start

data/lib/codepulse/base_client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Codepulse
+  # Shared GitHub API client logic for fetching PRs, reviews, and comments.
+  module BaseClient
+    REPO_FORMAT = %r{\A[^/]+/[^/]+\z}
+
+    # Fetches pull requests with pagination, then fetches full details for each.
+    def pull_requests(repository, state:, limit:)
+      ensure_repository_format(repository)
+      per_page = [limit, 100].min
+      page = 1
+      collected = []
+
+      while collected.length < limit
+        response = api_get(
+          "/repos/#{repository}/pulls",
+          state: state,
+          per_page: per_page,
+          page: page
+        )
+        break if response.empty?
+
+        collected.concat(response)
+        break if response.length < per_page
+
+        page += 1
+      end
+
+      limited = collected.first(limit)
+      fetch_pull_request_details(repository, limited)
+    end
+
+    def pull_request_reviews(repository, number)
+      ensure_repository_format(repository)
+      api_get("/repos/#{repository}/pulls/#{number}/reviews", per_page: 100)
+    end
+
+    def pull_request_comments(repository, number)
+      ensure_repository_format(repository)
+      api_get("/repos/#{repository}/pulls/#{number}/comments", per_page: 100)
+    end
+
+    def issue_comments(repository, number)
+      ensure_repository_format(repository)
+      api_get("/repos/#{repository}/issues/#{number}/comments", per_page: 100)
+    end
+
+    private
+
+    def api_get(_path, _query_params = {})
+      raise NotImplementedError, "Subclasses must implement api_get"
+    end
+
+    def ensure_repository_format(repository)
+      return if repository.to_s.match?(REPO_FORMAT)
+
+      raise ConfigurationError, "Repository must be in the format owner/name"
+    end
+
+    def fetch_pull_request_details(repository, pull_requests)
+      pull_requests.map do |pull_request|
+        api_get("/repos/#{repository}/pulls/#{pull_request["number"]}")
+      end
+    end
+
+    def parse_json(body)
+      return {} if body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => error
+      raise ApiError, "Failed to parse response: #{error.message}"
+    end
+
+    def encode_query(query_params)
+      return "" if query_params.empty?
+
+      "?#{URI.encode_www_form(query_params)}"
+    end
+  end
+end

data/lib/codepulse/cli.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "open3"
+require "json"
+
+module Codepulse
+  class CLI
+    include TimeHelpers
+
+    DEFAULT_STATE = "all"
+    DEFAULT_BUSINESS_DAYS = 7
+    PRS_PER_BUSINESS_DAY = 5
+    MAX_AUTO_LIMIT = 200
+
+    def self.start(argument_list = ARGV)
+      new(argument_list).run
+    end
+
+    def initialize(argument_list)
+      @argument_list = argument_list
+      @options = {
+        state: DEFAULT_STATE,
+        limit: nil,
+        gh_command: GhCliClient::DEFAULT_COMMAND,
+        business_days_back: DEFAULT_BUSINESS_DAYS,
+        details: false
+      }
+    end
+
+    def run
+      parse_options
+      validate_required_options
+
+      repo = @options.fetch(:repo)
+      client = GhCliClient.new(command: @options.fetch(:gh_command))
+
+      pull_requests = fetch_pull_requests(client, repo)
+      pull_requests = apply_filters(pull_requests)
+      metrics = calculate_metrics(client, repo, pull_requests)
+
+      clear_status
+      Formatter.new.output(
+        metrics,
+        repo: repo,
+        detailed: @options.fetch(:details),
+        business_days: @options.fetch(:business_days_back)
+      )
+    rescue OptionParser::ParseError => error
+      $stderr.puts "Error: #{error.message}"
+      $stderr.puts
+      $stderr.puts option_parser
+      exit 1
+    rescue ConfigurationError => error
+      $stderr.puts "Configuration error: #{error.message}"
+      exit 1
+    rescue ApiError => error
+      $stderr.puts "GitHub API error: #{error.message}"
+      exit 1
+    end
+
+    private
+
+    def parse_options
+      option_parser.parse!(@argument_list)
+      @options[:repo] = @argument_list.shift if @argument_list.any?
+      @options[:repo] ||= detect_repo_from_git
+    end
+
+    def option_parser
+      @option_parser ||= OptionParser.new do |parser|
+        parser.banner = "Usage: codepulse [options] [owner/repo]"
+
+        parser.on("-s", "--state STATE", "Pull request state: open, closed, all (default: #{DEFAULT_STATE})") do |state|
+          @options[:state] = state
+        end
+
+        parser.on("-l", "--limit COUNT", Integer, "Max PRs to fetch (default: auto based on business-days)") do |count|
+          @options[:limit] = count
+        end
+
+        parser.on("--gh-command PATH", "Path to gh executable (default: #{GhCliClient::DEFAULT_COMMAND})") do |path|
+          @options[:gh_command] = path
+        end
+
+        parser.on("--business-days DAYS", Integer, "PRs from last N business days (default: #{DEFAULT_BUSINESS_DAYS})") do |days|
+          @options[:business_days_back] = days
+        end
+
+        parser.on("--details", "Show per-PR detail table instead of summary") do
+          @options[:details] = true
+        end
+
+        parser.on("-h", "--help", "Show help") do
+          puts parser
+          exit
+        end
+      end
+    end
+
+    def validate_required_options
+      raise OptionParser::MissingArgument, "owner/repo is required" unless @options[:repo]
+
+      validate_state
+      validate_positive_integer(:limit, "limit")
+      validate_positive_integer(:business_days_back, "business-days")
+    end
+
+    def validate_state
+      return if %w[open closed all].include?(@options[:state])
+
+      raise OptionParser::InvalidArgument, "state must be open, closed, or all"
+    end
+
+    def validate_positive_integer(key, name)
+      value = @options[key]
+      return if value.nil?
+      return if value.is_a?(Integer) && value.positive?
+
+      raise OptionParser::InvalidArgument, "#{name} must be a positive integer"
+    end
+
+    def fetch_pull_requests(client, repo)
+      limit = effective_limit
+      status "Fetching pull requests from #{repo}..."
+      client.pull_requests(repo, state: @options.fetch(:state), limit: limit)
+    end
+
+    def effective_limit
+      return @options[:limit] if @options[:limit]
+
+      business_days = @options.fetch(:business_days_back)
+      calculated = business_days * PRS_PER_BUSINESS_DAY
+      [calculated, MAX_AUTO_LIMIT].min
+    end
+
+    def apply_filters(pull_requests)
+      status "Filtering #{pull_requests.length} pull requests..."
+      pull_requests = exclude_closed_unmerged(pull_requests)
+
+      cutoff_time = business_days_cutoff(@options[:business_days_back])
+      pull_requests = filter_by_business_days(pull_requests, cutoff_time) if cutoff_time
+      pull_requests
+    end
+
+    def calculate_metrics(client, repo, pull_requests)
+      status "Calculating metrics for #{pull_requests.length} pull requests..."
+      calculator = MetricsCalculator.new(client: client)
+
+      pull_requests.each_with_index.map do |pull_request, index|
+        status "  Analyzing PR ##{pull_request["number"]} (#{index + 1}/#{pull_requests.length})..."
+        calculator.metrics_for_pull_request(repo, pull_request)
+      end
+    end
+
+    def exclude_closed_unmerged(pull_requests)
+      pull_requests.reject do |pull_request|
+        pull_request["state"] == "closed" && pull_request["merged_at"].nil?
+      end
+    end
+
+    def filter_by_business_days(pull_requests, cutoff_time)
+      pull_requests.select do |pull_request|
+        created_at = parse_time(pull_request["created_at"])
+        created_at && created_at >= cutoff_time
+      end
+    end
+
+    def detect_repo_from_git
+      stdout, _stderr, status = Open3.capture3(@options[:gh_command], "repo", "view", "--json", "nameWithOwner")
+      return nil unless status.success?
+
+      data = JSON.parse(stdout)
+      data["nameWithOwner"]
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
+    def status(message)
+      $stderr.print "\r\e[K#{message}"
+    end
+
+    def clear_status
+      $stderr.print "\r\e[K"
+    end
+  end
+end

data/lib/codepulse/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Codepulse
+  class ConfigurationError < StandardError; end
+  class ApiError < StandardError; end
+end

data/lib/codepulse/formatter.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Codepulse
+  # Formats and outputs PR metrics as a terminal report.
+  class Formatter
+    REPORT_WIDTH = 86
+    TITLE_LIMIT = 50
+    MIN_FOR_P95 = 50 # Minimum data points to show p95
+
+    # Main entry point: outputs metrics as a formatted report.
+    def output(metrics, repo:, detailed: true, business_days: nil)
+      if metrics.empty?
+        puts "No pull requests found for #{repo}."
+        return
+      end
+
+      with_pickup = metrics.select { |metric| metric[:pickup_time_seconds] }
+      without_pickup = metrics.reject { |metric| metric[:pickup_time_seconds] }
+
+      output_report(
+        with_pickup,
+        excluded: without_pickup,
+        repo: repo,
+        business_days: business_days,
+        detailed: detailed
+      )
+    end
+
+    private
+
+    def output_report(metrics, excluded:, repo:, business_days:, detailed:)
+      print_report_header(repo, business_days)
+      puts
+      print_definitions
+      puts
+      print_summary(metrics, excluded: excluded)
+      print_details(metrics, excluded: excluded) if detailed
+    end
+
+    def print_definitions
+      puts "  Pickup time:    Time from PR creation to first reviewer response (business days, excl. US holidays)"
+      puts "  Time to merge:  Time from PR creation to merge (business days, excl. US holidays)"
+      puts "  PR size:        Net lines changed (additions - deletions)"
+      puts "  Files changed:  Number of files modified in the PR"
+    end
+
+    def print_summary(metrics, excluded:)
+      open_count = excluded.count { |m| m[:merged_at].nil? }
+      merged_count = excluded.count - open_count
+
+      excluded_text = build_excluded_text(open_count, merged_count)
+      print_section_title("SUMMARY (#{metrics.count} PRs with pickup#{excluded_text})")
+      puts
+
+      print_duration_stats("Pickup time", metrics.map { |m| m[:pickup_time_seconds] })
+      puts
+
+      print_duration_stats("Time to merge", metrics.map { |m| m[:merge_time_seconds] }.compact)
+      puts
+
+      print_number_stats("PR size (net lines)", metrics.map { |m| m[:additions].to_i - m[:deletions].to_i })
+      puts
+
+      print_number_stats("Files changed", metrics.map { |m| m[:changed_files].to_i })
+    end
+
+    def print_details(metrics, excluded:)
+      if metrics.any?
+        sorted = metrics.sort_by { |m| -(m[:pickup_time_seconds] || 0) }
+        puts
+        print_section_title("INDIVIDUAL PRs (slowest pickup first)")
+        puts
+        output_individual_prs(sorted)
+      end
+
+      return unless excluded.any?
+
+      puts
+      print_section_title("EXCLUDED PRs (no pickup yet)")
+      puts
+      output_excluded_prs(excluded)
+    end
+
+    def print_report_header(repo, business_days)
+      time_period = build_time_period(business_days)
+      puts "=" * REPORT_WIDTH
+      puts "  PR PICKUP TIME REPORT | #{time_period}"
+      puts "  #{repo}"
+      puts "=" * REPORT_WIDTH
+    end
+
+    def build_time_period(business_days)
+      return "all time" unless business_days
+
+      end_date = Time.now
+      start_date = calculate_start_date(business_days)
+      "Last #{business_days} business days (#{format_date(start_date)} - #{format_date(end_date)})"
+    end
+
+    def calculate_start_date(business_days)
+      current = Time.now
+      remaining = business_days
+
+      while remaining.positive?
+        current -= 86_400
+        remaining -= 1 if weekday?(current)
+      end
+
+      current
+    end
+
+    def weekday?(time_value)
+      time_value.wday.between?(1, 5)
+    end
+
+    def format_date(time_value)
+      time_value.strftime("%b %-d")
+    end
+
+    def build_excluded_text(open_count, merged_count)
+      parts = []
+      parts << "#{open_count} awaiting pickup" if open_count.positive?
+      parts << "#{merged_count} merged without pickup" if merged_count.positive?
+
+      return "" if parts.empty?
+
+      ", #{parts.join(", ")}"
+    end
+
+    def print_section_title(title)
+      puts "-" * REPORT_WIDTH
+      puts "  #{title}"
+      puts "-" * REPORT_WIDTH
+    end
+
+    def output_individual_prs(metrics)
+      pr_width = 8
+      pickup_width = 12
+      merge_width = 12
+      lines_width = 10
+      author_width = 16
+
+      header = [
+        "PR".ljust(pr_width),
+        "PICKUP".ljust(pickup_width),
+        "MERGE".ljust(merge_width),
+        "LINES".ljust(lines_width),
+        "AUTHOR".ljust(author_width),
+        "TITLE"
+      ].join("  ")
+      puts "  #{header}"
+
+      metrics.each do |metric|
+        net_lines = metric[:additions].to_i - metric[:deletions].to_i
+        merge_time = metric[:merge_time_seconds] ? format_duration_compact(metric[:merge_time_seconds]) : "—"
+
+        row = [
+          "##{metric.fetch(:number)}".ljust(pr_width),
+          format_duration_compact(metric[:pickup_time_seconds]).ljust(pickup_width),
+          merge_time.ljust(merge_width),
+          size_string(net_lines).ljust(lines_width),
+          metric.fetch(:author, "unknown").to_s.ljust(author_width),
+          truncate(metric.fetch(:title).to_s, 40)
+        ].join("  ")
+        puts "  #{row}"
+      end
+    end
+
+    def output_excluded_prs(metrics)
+      pr_width = 10
+      age_width = 14
+      author_width = 20
+
+      header = [
+        "PR".ljust(pr_width),
+        "AGE".ljust(age_width),
+        "AUTHOR".ljust(author_width),
+        "TITLE"
+      ].join("  ")
+      puts "  #{header}"
+
+      metrics.each do |metric|
+        age = metric[:created_at] ? time_ago(metric[:created_at]) : "unknown"
+        row = [
+          "##{metric.fetch(:number)}".ljust(pr_width),
+          age.ljust(age_width),
+          metric.fetch(:author, "unknown").to_s.ljust(author_width),
+          truncate(metric.fetch(:title).to_s, 50)
+        ].join("  ")
+        puts "  #{row}"
+      end
+    end
+
+    def print_duration_stats(label, values)
+      return puts("  #{label}: none") if values.empty?
+
+      sorted = values.sort
+      average_seconds = (values.sum / values.length.to_f).round
+
+      puts "  Average #{label.downcase}:  #{format_duration_compact(average_seconds)}"
+      puts "  Median #{label.downcase}:   #{format_duration_compact(percentile_value(sorted, 50))}"
+      puts "  p95 #{label.downcase}:      #{format_duration_compact(percentile_value(sorted, 95))}" if values.length >= MIN_FOR_P95
+      puts "  Fastest #{label.downcase}: #{format_duration_compact(sorted.first)}"
+      puts "  Slowest #{label.downcase}: #{format_duration_compact(sorted.last)}"
+    end
+
+    def print_number_stats(label, values)
+      return puts("  #{label}: none") if values.empty?
+
+      sorted = values.sort
+      average_value = (values.sum / values.length.to_f).round(1)
+
+      puts "  Average #{label.downcase}:  #{format_number_compact(average_value)}"
+      puts "  Median #{label.downcase}:   #{format_number_compact(percentile_value(sorted, 50))}"
+      puts "  p95 #{label.downcase}:      #{format_number_compact(percentile_value(sorted, 95))}" if values.length >= MIN_FOR_P95
+      puts "  Min #{label.downcase}:      #{format_number_compact(sorted.first)}"
+      puts "  Max #{label.downcase}:      #{format_number_compact(sorted.last)}"
+    end
+
+    def truncate(value, length)
+      return value if value.length <= length
+
+      "#{value[0, length - 1]}…"
+    end
+
+    def size_string(net_lines)
+      return "0" if net_lines.zero?
+
+      net_lines.positive? ? "+#{net_lines}" : net_lines.to_s
+    end
+
+    def format_duration_compact(seconds)
+      seconds = seconds.to_i
+      return "0m" if seconds <= 0
+
+      total_minutes = (seconds / 60.0).round
+      minutes = total_minutes % 60
+      total_hours = total_minutes / 60
+      hours = total_hours % 24
+      days = total_hours / 24
+
+      if days.positive?
+        hours_part = hours.positive? ? " #{hours}h" : ""
+        "#{days}d#{hours_part}"
+      elsif total_hours.positive?
+        minutes_part = minutes.positive? ? " #{minutes}m" : ""
+        "#{total_hours}h#{minutes_part}"
+      else
+        "#{minutes}m"
+      end
+    end
+
+    def time_ago(time_value)
+      seconds = Time.now - time_value
+      return "#{seconds.to_i}s ago" if seconds < 60
+
+      minutes = seconds / 60
+      return "#{minutes.round}m ago" if minutes < 60
+
+      hours = minutes / 60
+      return "#{hours.round}h ago" if hours < 48
+
+      days = hours / 24
+      "#{days.round}d ago"
+    end
+
+    # Returns the value at the given percentile from a sorted array.
+    # Uses nearest-rank method: p50 = median, p95 = 95th percentile.
+    def percentile_value(sorted_values, percentile)
+      count = sorted_values.length
+      rank = (percentile / 100.0 * count).ceil
+      index = [rank - 1, count - 1].min
+      sorted_values[index]
+    end
+
+    def format_number_compact(value)
+      return "0" if value.nil?
+
+      if value.is_a?(Float) && value % 1 != 0
+        value.round(1).to_s
+      else
+        value.to_i.to_s
+      end
+    end
+  end
+end

data/lib/codepulse/gh_cli_client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Codepulse
+  class GhCliClient
+    include BaseClient
+
+    DEFAULT_COMMAND = "gh"
+
+    def initialize(command: DEFAULT_COMMAND)
+      @command = command
+      verify_cli_available
+    end
+
+    private
+
+    def api_get(path, query_params = {})
+      full_path = "#{path}#{encode_query(query_params)}"
+      stdout, stderr, status = Open3.capture3(@command, "api", full_path)
+
+      unless status.success?
+        message = stderr.to_s.strip.empty? ? stdout.to_s.strip : stderr.to_s.strip
+        raise ApiError, "gh api #{full_path} failed: #{message}"
+      end
+
+      parse_json(stdout)
+    rescue Errno::ENOENT
+      raise ConfigurationError, "gh CLI not found. Install it from https://cli.github.com and run `gh auth login`."
+    end
+
+    def verify_cli_available
+      _stdout, _stderr, status = Open3.capture3(@command, "auth", "status")
+      return if status.success?
+
+      raise ConfigurationError, "gh CLI not authenticated. Run `gh auth login` first."
+    rescue Errno::ENOENT
+      raise ConfigurationError, "gh CLI not found. Install it from https://cli.github.com and run `gh auth login`."
+    end
+  end
+end

data/lib/codepulse/metrics_calculator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Codepulse
+  # Calculates pickup time, merge time, and size metrics for pull requests.
+  class MetricsCalculator
+    include TimeHelpers
+
+    # Bot accounts to ignore when calculating pickup time.
+    IGNORED_ACTORS = [
+      "copilot-pull-request-reviewer",
+      "copilot-pull-request-reviewer[bot]",
+      "copilot",
+      "copilot[bot]",
+      "copilot-bot",
+      "github-copilot",
+      "github-copilot[bot]",
+      "github-actions",
+      "github-actions[bot]"
+    ].freeze
+
+    def initialize(client:)
+      @client = client
+    end
+
+    # Returns a hash of metrics for a single PR.
+    def metrics_for_pull_request(repository, pull_request)
+      created_at = parse_time(pull_request["created_at"])
+      merged_at = parse_time(pull_request["merged_at"])
+      pickup_event = find_pickup_event(repository, pull_request, created_at)
+      pickup_seconds = pickup_event ? business_seconds_between(created_at, pickup_event.fetch(:timestamp)) : nil
+      merge_seconds = merged_at && created_at ? business_seconds_between(created_at, merged_at) : nil
+
+      {
+        number: pull_request["number"],
+        title: pull_request["title"],
+        author: pull_request.dig("user", "login"),
+        created_at: created_at,
+        merged_at: merged_at,
+        additions: pull_request["additions"].to_i,
+        deletions: pull_request["deletions"].to_i,
+        changed_files: pull_request["changed_files"].to_i,
+        pickup_time_seconds: pickup_seconds,
+        merge_time_seconds: merge_seconds,
+        pickup_actor: pickup_event&.fetch(:actor, nil),
+        pickup_at: pickup_event&.fetch(:timestamp, nil),
+        pickup_source: pickup_event&.fetch(:source, nil)
+      }
+    end
+
+    private
+
+    # Finds the first non-author, non-bot response (review, comment, or issue comment).
+    def find_pickup_event(repository, pull_request, created_at)
+      pull_number = pull_request["number"]
+      author_login = pull_request.dig("user", "login")
+
+      review_event = earliest_event(
+        @client.pull_request_reviews(repository, pull_number),
+        author_login: author_login,
+        time_key: "submitted_at",
+        actor_path: %w[user login],
+        source: "review"
+      )
+
+      review_comment_event = earliest_event(
+        @client.pull_request_comments(repository, pull_number),
+        author_login: author_login,
+        time_key: "created_at",
+        actor_path: %w[user login],
+        source: "review_comment"
+      )
+
+      issue_comment_event = earliest_event(
+        @client.issue_comments(repository, pull_number),
+        author_login: author_login,
+        time_key: "created_at",
+        actor_path: %w[user login],
+        source: "issue_comment"
+      )
+
+      [review_event, review_comment_event, issue_comment_event]
+        .compact
+        .select { |event| event.fetch(:timestamp) && created_at }
+        .min_by { |event| event.fetch(:timestamp) }
+    end
+
+    def earliest_event(events, author_login:, time_key:, actor_path:, source:)
+      events
+        .map { |event| build_event(event, author_login: author_login, time_key: time_key, actor_path: actor_path, source: source) }
+        .compact
+        .min_by { |event| event.fetch(:timestamp) }
+    end
+
+    def build_event(event, author_login:, time_key:, actor_path:, source:)
+      actor_login = dig_path(event, actor_path)
+      return nil if actor_login.nil?
+
+      normalized_actor = normalize_actor(actor_login)
+      normalized_author = normalize_actor(author_login)
+
+      return nil if normalized_actor.nil?
+      return nil if normalized_actor == normalized_author
+      return nil if IGNORED_ACTORS.include?(normalized_actor)
+
+      timestamp = parse_time(event[time_key])
+      return nil unless timestamp
+
+      {
+        actor: actor_login,
+        timestamp: timestamp,
+        source: source
+      }
+    end
+
+    def dig_path(hash, path)
+      path.reduce(hash) { |value, key| value.is_a?(Hash) ? value[key] : nil }
+    end
+
+    def normalize_actor(value)
+      value.to_s.downcase.strip
+    end
+  end
+end

data/lib/codepulse/time_helpers.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Codepulse
+  # Time calculation helpers for business days and holidays.
+  module TimeHelpers
+    SECONDS_PER_DAY = 86_400
+
+    # Parses a time string, returns nil if invalid.
+    def parse_time(value)
+      Time.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # Returns true if the time falls on a weekday and is not a US holiday.
+    def business_day?(time_value)
+      return false unless weekday?(time_value)
+      return false if us_holiday?(time_value)
+
+      true
+    end
+
+    # Returns true for Monday through Friday.
+    def weekday?(time_value)
+      time_value.wday.between?(1, 5)
+    end
+
+    # Returns true if the date is a US federal holiday.
+    def us_holiday?(time_value)
+      us_holidays(time_value.year).include?(date_key(time_value))
+    end
+
+    def date_key(time_value)
+      [time_value.year, time_value.month, time_value.day]
+    end
+
+    def us_holidays(year)
+      @us_holidays_cache ||= {}
+      @us_holidays_cache[year] ||= build_us_holidays(year)
+    end
+
+    def build_us_holidays(year)
+      holidays = []
+
+      # New Year's Day (Jan 1)
+      holidays << [year, 1, 1]
+
+      # MLK Day (3rd Monday in January)
+      holidays << nth_weekday(year, 1, 1, 3)
+
+      # Presidents Day (3rd Monday in February)
+      holidays << nth_weekday(year, 2, 1, 3)
+
+      # Memorial Day (last Monday in May)
+      holidays << last_weekday(year, 5, 1)
+
+      # Juneteenth (June 19)
+      holidays << [year, 6, 19]
+
+      # Independence Day (July 4)
+      holidays << [year, 7, 4]
+
+      # Labor Day (1st Monday in September)
+      holidays << nth_weekday(year, 9, 1, 1)
+
+      # Columbus Day (2nd Monday in October)
+      holidays << nth_weekday(year, 10, 1, 2)
+
+      # Veterans Day (Nov 11)
+      holidays << [year, 11, 11]
+
+      # Thanksgiving (4th Thursday in November)
+      holidays << nth_weekday(year, 11, 4, 4)
+
+      # Christmas Day (Dec 25)
+      holidays << [year, 12, 25]
+
+      holidays
+    end
+
+    # Finds the nth occurrence of a weekday in a month (e.g., 3rd Monday).
+    # target_wday: 0=Sun, 1=Mon, ..., 6=Sat
+    def nth_weekday(year, month, target_wday, occurrence)
+      first_day = Time.new(year, month, 1)
+      days_until = (target_wday - first_day.wday + 7) % 7
+      day = 1 + days_until + (7 * (occurrence - 1))
+      [year, month, day]
+    end
+
+    # Finds the last occurrence of a weekday in a month (e.g., last Monday of May).
+    def last_weekday(year, month, target_wday)
+      next_month = month == 12 ? Time.new(year + 1, 1, 1) : Time.new(year, month + 1, 1)
+      last_day = next_month - SECONDS_PER_DAY
+      days_back = (last_day.wday - target_wday + 7) % 7
+      [year, month, last_day.day - days_back]
+    end
+
+    def start_of_day(time_value)
+      Time.new(time_value.year, time_value.month, time_value.day, 0, 0, 0, time_value.utc_offset)
+    end
+
+    def end_of_day(time_value)
+      Time.new(time_value.year, time_value.month, time_value.day, 23, 59, 59, time_value.utc_offset)
+    end
+
+    # Calculates seconds between two times, counting only business day hours.
+    # Skips weekends and US holidays entirely.
+    def business_seconds_between(start_time, end_time)
+      return nil unless start_time && end_time
+      return 0 if end_time <= start_time
+
+      total = 0
+      current_start = start_time
+
+      while current_start < end_time
+        day_end = end_of_day(current_start)
+        segment_end = [day_end, end_time].min
+
+        total += (segment_end - current_start) if business_day?(current_start)
+
+        current_start = start_of_day(current_start + SECONDS_PER_DAY)
+      end
+
+      total.to_i
+    end
+
+    # Returns the cutoff time for N business days ago.
+    def business_days_cutoff(business_days)
+      return nil unless business_days
+
+      current_time = Time.now
+      remaining_days = business_days
+
+      while remaining_days.positive?
+        current_time -= SECONDS_PER_DAY
+        remaining_days -= 1 if business_day?(current_time)
+      end
+
+      start_of_day(current_time)
+    end
+  end
+end

data/lib/codepulse.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "codepulse/errors"
+require_relative "codepulse/time_helpers"
+require_relative "codepulse/base_client"
+require_relative "codepulse/gh_cli_client"
+require_relative "codepulse/metrics_calculator"
+require_relative "codepulse/formatter"
+require_relative "codepulse/cli"
+
+module Codepulse
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: codepulse
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrick Navarro
+bindir: bin
+cert_chain: []
+date: 2025-12-24 00:00:00.000000000 Z
+dependencies: []
+description: Terminal tool to analyze GitHub pull request pickup times, merge times,
+  and sizes using the gh CLI.
+email:
+- patrick@workbright.com
+executables:
+- codepulse
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/codepulse
+- lib/codepulse.rb
+- lib/codepulse/base_client.rb
+- lib/codepulse/cli.rb
+- lib/codepulse/errors.rb
+- lib/codepulse/formatter.rb
+- lib/codepulse/gh_cli_client.rb
+- lib/codepulse/metrics_calculator.rb
+- lib/codepulse/time_helpers.rb
+homepage: https://github.com/WorkBright/codepulse
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/WorkBright/codepulse
+  source_code_uri: https://github.com/WorkBright/codepulse
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: GitHub PR metrics TUI app
+test_files: []