Class: Homebrew::DevCmd::Contributions Private

Inherits:

AbstractCommand

Object
AbstractCommand
Homebrew::DevCmd::Contributions

show all

Includes:: SystemCommand::Mixin

Defined in:: dev-cmd/contributions.rb,
sorbet/rbi/dsl/homebrew/dev_cmd/contributions.rbi

This class is part of a private API. This class may only be used in the Homebrew/brew repository. Third parties should avoid using this class if possible, as it may be removed or changed without warning.

Defined Under Namespace

Classes: Args

Constant Summary collapse

PRIMARY_REPOS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

%w[
  Homebrew/brew
  Homebrew/homebrew-core
  Homebrew/homebrew-cask
].freeze

CONTRIBUTION_TYPES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

T.let({
  merged_pr_author:   "merged PRs authored",
  merged_pr_merger:   "PRs merged",
  merged_pr:          "qualifying merged PRs",
  approved_pr_review: "approved-review search matches",
  coauthor:           "co-authored commits",
}.freeze, T::Hash[Symbol, String])

MAX_PR_SEARCH =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

ACTIVITY_PERIOD_MONTHS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

https://docs.brew.sh/Homebrew-Governance#maintainer

MAINTAINER_ACTIVITY_THRESHOLD =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

LEAD_ACTIVITY_PERIODS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

https://docs.brew.sh/Homebrew-Governance#lead-maintainer

LEAD_REPOSITORY_ACTIVITY_THRESHOLD =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

MAX_CONTRIBUTIONS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

T.let(MAINTAINER_ACTIVITY_THRESHOLD * 10, Integer)

QUALIFYING_CONTRIBUTION_TYPES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

[:merged_pr, :approved_pr_review, :coauthor].freeze

GIT_LOG_FIELD_SEPARATOR =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"\x1f"

GIT_LOG_RECORD_SEPARATOR =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"\x1e"

GIT_LOG_COMMIT_HASH_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%H"

GIT_LOG_PARENT_HASHES_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%P"

GIT_LOG_AUTHOR_NAME_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%an"

GIT_LOG_AUTHOR_EMAIL_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%ae"

GIT_LOG_COMMITTER_NAME_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%cn"

GIT_LOG_COMMITTER_EMAIL_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%ce"

GIT_LOG_COMMITTER_DATE_SHORT_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%cs"

GIT_LOG_COMMIT_MESSAGE_FORMAT =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

"%B"

GIT_LOG_FIELDS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

T.let({
  commit_hash: 0, parent_hashes: 1, author_name: 2, author_email: 3,
  committer_name: 4, committer_email: 5, commit_message: 6
}.freeze, T::Hash[Symbol, Integer])

Instance Method Summary collapse

#args ⇒ Homebrew::DevCmd::Contributions::Args private
#cached_github_request(type, *key_parts, to:, &block) ⇒ T.type_parameter(:U) private
Returns the block's result, caching it as JSON for completed periods and waiting out rate limits.
#github_identities_for_username(username, to:) ⇒ Array<String> private
#github_username_for(user, to:) ⇒ String^? private
#maintainer_activity_report(from, to, current_report: nil) ⇒ Hash{String => Array<(Boolean, Boolean)>}^? private
#maintainer_report_users(repository_refs, to) ⇒ Array<(Hash{String => String}, Hash{String => Boolean}, Hash{String => String, nil})> private
#maintainer_since(repository_path, ref, user, name) ⇒ String^? private
#parse_git_log(output, users, github_identities: nil, authored_pull_requests: nil, merged_pull_requests: nil) ⇒ Hash{String => Hash{Symbol => Integer}} private
#potential_maintainer_role(user, role, maintainer_since_date, period_end, activity, previous_reports) ⇒ String^? private
#previous_maintainer_reports(from) ⇒ Array<Hash{String => Array<(Boolean, Boolean)>}> private
#run ⇒ void private
#scan_contributions(organisation, repositories, repository_refs, users, from:, to:, skip_reviews_if_lead_met:, progress:) ⇒ Hash{String => Hash{String => Hash{Symbol => Integer}}} private

Constructor Details

This class inherits a constructor from Homebrew::AbstractCommand

Instance Method Details

#args ⇒ `Homebrew::DevCmd::Contributions::Args`

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

(Homebrew::DevCmd::Contributions::Args)

10	# File 'sorbet/rbi/dsl/homebrew/dev_cmd/contributions.rbi', line 10 def args; end

#cached_github_request(type, *key_parts, to:, &block) ⇒ `T.type_parameter(:U)`

Returns the block's result, caching it as JSON for completed periods and waiting out rate limits. type is the JSON class the block returns so unexpected cached data is discarded rather than returned.

Parameters:

type (T::Class[T.type_parameter(:U)])
key_parts (String)
to (String)
block (T.proc.returns(T.type_parameter(:U)))

Returns:

(T.type_parameter(:U))

# File 'dev-cmd/contributions.rb', line 556

def cached_github_request(type, *key_parts, to:, &block)
  cache_path = if Date.iso8601(to) <= Date.today
    # NUL cannot appear in usernames, repositories or dates so joining with it keeps key parts distinct.
    cache_key = ["1", *key_parts].join("\0")
    HOMEBREW_CACHE/"contributions--#{Digest::SHA256.hexdigest(cache_key)}.json"
  end
  if cache_path&.file?
    begin
      cached = JSON.parse(cache_path.read)
      return cached if cached.is_a?(type)

      opoo "Deleting contributions cache #{cache_path} containing #{cached.class} rather than #{type}."
    rescue JSON::ParserError, Errno::ENOENT => e
      opoo "Deleting unreadable contributions cache #{cache_path}: #{e}"
    end
    cache_path.unlink if cache_path.exist?
  end

  result = yield
  if cache_path
    HOMEBREW_CACHE.mkpath
    cache_path.atomic_write(JSON.generate(result))
  end
  result
rescue GitHub::API::RateLimitExceededError => e
  GitHub::API.sleep_for_rate_limit(e)
  retry
end

#github_identities_for_username(username, to:) ⇒ `Array<String>`

Parameters:

username (String)
to (String)

Returns:

(Array<String>)

# File 'dev-cmd/contributions.rb', line 537

def github_identities_for_username(username, to:)
  profile = cached_github_request(Hash, "user-profile", username, to, to:) do
    GitHub::API.open_rest(GitHub.url_to("users", username))
  rescue GitHub::API::HTTPNotFoundError
    {}
  end
  [username, profile["name"], profile["email"]].compact
end

#github_username_for(user, to:) ⇒ `String`^?

Parameters:

user (String)
to (String)

Returns:

(String, nil)

# File 'dev-cmd/contributions.rb', line 515

def github_username_for(user, to:)
  return user unless user.include?("@")

  noreply_username = github_noreply_username(user)
  return noreply_username if noreply_username

  matches = cached_github_request(Array, "public-email", user, to, to:) do
    GitHub.search("users", "\"#{user}\" in:email").fetch("items", [])
  end
  if matches.one?
    login = matches.fetch(0)["login"]
    return login if login.is_a?(String)
  end

  opoo "Could not find a unique public GitHub account for #{user}; skipping GitHub PR searches."
  nil
rescue GitHub::API::ValidationFailedError
  opoo "Could not search for a public GitHub account for #{user}; skipping GitHub PR searches."
  nil
end

#maintainer_activity_report(from, to, current_report: nil) ⇒ `Hash{String => Array<(Boolean, Boolean)>}`^?

Parameters:

from (String)
to (String)
current_report (Array<(String, String, Hash{String => Hash{String => Integer}})>, nil) (defaults to: nil)

Returns:

(Hash{String => Array<(Boolean, Boolean)>}, nil)

# File 'dev-cmd/contributions.rb', line 726

def maintainer_activity_report(from, to, current_report: nil)
  require "csv"

  reports = T.let([], T::Array[T::Hash[String, T::Hash[String, Integer]]])
  while from < to
    if current_report && current_report[0] == from && current_report[1] <= to
      reports << current_report[2]
      from = current_report[1]
      next
    end

    report_to, path = Dir["brew-contributions-#{from}-to-*.csv"].filter_map do |file|
      date = file[/\Abrew-contributions-\d{4}-\d{2}-\d{2}-to-(\d{4}-\d{2}-\d{2})\.csv\z/, 1]
      [date, file] if date && date > from && date <= to
    end.max
    return if path.nil? || report_to.nil?

    totals = T.let({}, T::Hash[String, T::Hash[String, Integer]])
    CSV.foreach(path, headers: true) do |row|
      next unless row.is_a?(CSV::Row)

      username = row["username"]
      next unless username.is_a?(String)

      totals[username.downcase] = PRIMARY_REPOS.to_h do |repository|
        [repository,
         Integer(row.fetch("#{repository.delete_prefix("Homebrew/").delete_prefix("homebrew-")} total"))]
      end
    end
    reports << totals
    from = report_to
  end
  reports.fetch(0).keys.filter_map do |user|
    next unless reports.all? { |report| report.key?(user) }

    user_totals = PRIMARY_REPOS.map do |repository|
      reports.sum { |report| report.fetch(user).fetch(repository) }
    end
    [user, [user_totals.sum >= MAINTAINER_ACTIVITY_THRESHOLD,
            user_totals.count { |total| total >= LEAD_REPOSITORY_ACTIVITY_THRESHOLD } >= 2]]
  end.to_h
end

#maintainer_report_users(repository_refs, to) ⇒ `Array<(Hash{String => String}, Hash{String => Boolean}, Hash{String => String, nil})>`

Parameters:

repository_refs (Hash{String => Array<(Pathname, String)>})
to (String)

Returns:

(Array<(Hash{String => String}, Hash{String => Boolean}, Hash{String => String, nil})>)

# File 'dev-cmd/contributions.rb', line 269

def maintainer_report_users(repository_refs, to)
  brew_path, brew_ref = repository_refs.fetch("Homebrew/brew")
  require "utils/git"
  period_end_ref = Utils.safe_popen_read(
    Utils::Git.git, "-C", brew_path, "rev-list", "-1", "--before=#{to}", brew_ref, "--", "README.md"
  ).strip
  odie "Could not find Homebrew/brew's README at the end of the reporting period." if period_end_ref.empty?

  user_names = T.let({}, T::Hash[String, String])
  lead_maintainers = T.let({}, T::Hash[String, T::Boolean])
  Utils.safe_popen_read(Utils::Git.git, "-C", brew_path, "show", "#{period_end_ref}:README.md")
       .dup.force_encoding(Encoding::UTF_8).each_line do |line|
    lead = line.start_with?("Homebrew's [Lead Maintainers]")
    next if !lead &&
            !line.start_with?("Homebrew's other Maintainers") &&
            !line.start_with?("Homebrew's maintainers are")

    line.scan(%r{\[([^\]]+)\]\(https://github\.com/([A-Za-z\d-]+)\)}).each do |match|
      next unless match.is_a?(Array)

      name = match.fetch(0)
      user = match.fetch(1)
      user_names[user] = name
      lead_maintainers[user.downcase] = true if lead
    end
  end
  odie "Could not read the maintainers from Homebrew/brew's README." if user_names.empty?

  if (users = args.user.presence)
    requested_usernames = users.to_h do |user|
      [user, github_username_for(user, to:)&.downcase]
    end
    unresolved_users = requested_usernames.filter_map { |user, username| user if username.nil? }
    odie "Could not resolve GitHub usernames for: #{Utils::Text.to_sentence(unresolved_users)}." \
      if unresolved_users.present?

    maintainer_usernames = user_names.keys.map(&:downcase)
    non_maintainers = requested_usernames.filter_map do |user, username|
      user if username && maintainer_usernames.exclude?(username)
    end
    unless non_maintainers.empty?
      odie "Not listed as #{Utils.pluralize("Maintainer", non_maintainers.length)} at the end of the " \
           "reporting period: #{Utils::Text.to_sentence(non_maintainers)}."
    end

    selected_usernames = requested_usernames.values.compact
    user_names.select! { |user| selected_usernames.include?(user.downcase) }
  end

  maintainer_count = Utils.pluralize("maintainer", user_names.length, include_count: true)
  $stderr.puts "Scanning contributions for #{maintainer_count}..."
  maintainer_since_dates = user_names.to_h do |user, name|
    [user, maintainer_since(brew_path, period_end_ref, user, name)]
  end
  [user_names, lead_maintainers, maintainer_since_dates]
end

#maintainer_since(repository_path, ref, user, name) ⇒ `String`^?

Parameters:

repository_path (Pathname)
ref (String)
user (String)
name (String)

Returns:

(String, nil)

# File 'dev-cmd/contributions.rb', line 327

def maintainer_since(repository_path, ref, user, name)
  require "utils/git"

  git_log_format = [GIT_LOG_COMMIT_HASH_FORMAT, GIT_LOG_COMMITTER_DATE_SHORT_FORMAT]
                   .join(GIT_LOG_FIELD_SEPARATOR)
  candidates = ["https://github.com/#{user}", name].flat_map do |identity|
    Utils.safe_popen_read(
      Utils::Git.git, "-C", repository_path, "log", ref, "--fixed-strings",
      "-S#{identity}", "--format=#{git_log_format}", "--", "README.md"
    ).lines(chomp: true)
  end
  candidates.uniq!
  candidates.sort_by! { |candidate| candidate.split(GIT_LOG_FIELD_SEPARATOR, 2).fetch(1) }
  candidates.each do |candidate|
    commit, date = candidate.split(GIT_LOG_FIELD_SEPARATOR, 2)
    next if date.nil?

    readme = Utils.safe_popen_read(Utils::Git.git, "-C", repository_path, "show", "#{commit}:README.md")
    parent_readme = system_command(Utils::Git.git,
                                   args:         ["-C", repository_path, "show", "#{commit}^:README.md"],
                                   print_stderr: false).stdout
    return date if readme_mentions?(readme, user, name) && !readme_mentions?(parent_readme, user, name)
  end

  nil
end

#parse_git_log(output, users, github_identities: nil, authored_pull_requests: nil, merged_pull_requests: nil) ⇒ `Hash{String => Hash{Symbol => Integer}}`

Parameters:

output (String)
users (Hash{String => String})
github_identities (Hash{String => Array<String>}, nil) (defaults to: nil)
authored_pull_requests (Hash{String => Set<String>}, nil) (defaults to: nil)
merged_pull_requests (Hash{String => Set<String>}, nil) (defaults to: nil)

Returns:

(Hash{String => Hash{Symbol => Integer}})

# File 'dev-cmd/contributions.rb', line 595

def parse_git_log(output, users, github_identities: nil, authored_pull_requests: nil, merged_pull_requests: nil)
  counts = users.to_h do |user, _|
    [user, CONTRIBUTION_TYPES.keys.to_h { |type| [type, 0] }]
  end
  identity_users = T.let({}, T::Hash[String, String])
  users.each do |user, name|
    identity_users[user.downcase] = user
    identity_users[name.downcase] = user
  end
  # GitHub profile names are not unique so only match those belonging to one requested user.
  github_identity_users = T.let({}, T::Hash[String, T.nilable(String)])
  github_identities&.each do |user, identities|
    identities.map(&:downcase).uniq.each do |identity|
      github_identity_users[identity] = github_identity_users.key?(identity) ? nil : user
    end
  end
  github_identity_users.each do |identity, user|
    identity_users[identity] ||= user if user
  end
  records = output.split(GIT_LOG_RECORD_SEPARATOR).filter_map do |record|
    values = record.strip.split(GIT_LOG_FIELD_SEPARATOR, GIT_LOG_FIELDS.length)
    next if values.length != GIT_LOG_FIELDS.length

    GIT_LOG_FIELDS.to_h { |field, index| [field, values.fetch(index)] }
  end
  record_identities = records.to_h do |fields|
    [fields.fetch(:commit_hash), [fields.fetch(:author_name), fields.fetch(:author_email)]]
  end

  # Resolve identities for each commit based on the author and committer information
  records.each do |fields|
    parents = fields.fetch(:parent_hashes).split
    source_owner = fields.fetch(:commit_message)[%r{\AMerge pull request #\d+ from ([^/\s]+)/}, 1]
    next if parents.length < 2 || source_owner.nil?

    user = identity_users[source_owner.downcase]
    source_identity = record_identities[parents.fetch(1)]
    next if user.nil? || source_identity.nil?

    name, email = source_identity
    identity_users[name.strip.downcase] ||= user
    identity_users[email.downcase] ||= user
  end

  # Map commit SHAs to their respective authors based on identity resolution
  commit_authors = T.let(records.to_h do |fields|
    [fields.fetch(:commit_hash), user_for_git_identity(
      fields.fetch(:author_name), fields.fetch(:author_email), identity_users
    )]
  end, T::Hash[String, T.nilable(String)])

  # Coauthor contributions with "Co-authored-by" in body
  records.each do |fields|
    coauthors = fields.fetch(:commit_message)
                      .scan(/^Co-authored-by:\s*(.*?)\s*<([^>]+)>/i).filter_map do |match|
      next unless match.is_a?(Array)

      user_for_git_identity(match.fetch(0), match.fetch(1), identity_users)
    end

    # Coauthor information from amended commit fields
    if [fields.fetch(:author_name), fields.fetch(:author_email)] !=
       [fields.fetch(:committer_name), fields.fetch(:committer_email)]
      coauthor = user_for_git_identity(
        fields.fetch(:committer_name), fields.fetch(:committer_email), identity_users
      )
      coauthors << coauthor if coauthor
    end

    # Increment coauthor contribution counts
    coauthors.uniq.each do |user|
      increment_contribution_count(counts.fetch(user), :coauthor)
    end

    parents = fields.fetch(:parent_hashes).split
    pull_request = fields.fetch(:commit_message).match(%r{\AMerge pull request #(\d+) from ([^/\s]+)/})
    next if parents.length < 2 || pull_request.nil?

    merger = user_for_git_identity(fields.fetch(:author_name), fields.fetch(:author_email), identity_users)
    pull_request_id = pull_request[1]
    source_owner = pull_request[2]
    next if pull_request_id.nil? || source_owner.nil?

    author = identity_users[source_owner.downcase] || commit_authors[parents.fetch(1)]
    if author
      increment_contribution_count(counts.fetch(author), :merged_pr_author)
      authored_pull_requests&.fetch(author)&.add(pull_request_id)
    end
    increment_contribution_count(counts.fetch(merger), :merged_pr_merger) if merger
    [author, merger].compact.uniq.each do |user|
      increment_contribution_count(counts.fetch(user), :merged_pr)
      merged_pull_requests&.fetch(user)&.add(pull_request_id)
    end
  end

  counts
end

#potential_maintainer_role(user, role, maintainer_since_date, period_end, activity, previous_reports) ⇒ `String`^?

Parameters:

user (String)
role (String)
maintainer_since_date (Date, nil)
period_end (Date)
activity (Array<(Boolean, Boolean)>)
previous_reports (Array<Hash{String => Array<(Boolean, Boolean)>}>)

Returns:

(String, nil)

# File 'dev-cmd/contributions.rb', line 779

def potential_maintainer_role(user, role, maintainer_since_date, period_end, activity, previous_reports)
  maintainer_activity_met, lead_activity_met = activity
  previous_activity = previous_reports.first&.[](user.downcase)
  return if previous_activity.nil?

  return "None" if !maintainer_activity_met && !previous_activity.fetch(0)

  if role == "Lead Maintainer"
    return "Maintainer" if !lead_activity_met && !previous_activity.fetch(1)

    return role
  end

  return role if maintainer_since_date.nil? || maintainer_since_date > period_end.prev_year(3)
  return role unless lead_activity_met

  previous_lead_activity = previous_reports.map { |report| report[user.downcase]&.fetch(1) }
  return if previous_lead_activity.length < LEAD_ACTIVITY_PERIODS - 1 || previous_lead_activity.any?(&:nil?)

  previous_lead_activity.all?(true) ? "Lead Maintainer" : role
end

#previous_maintainer_reports(from) ⇒ `Array<Hash{String => Array<(Boolean, Boolean)>}>`

Parameters:

from (String)

Returns:

(Array<Hash{String => Array<(Boolean, Boolean)>}>)

# File 'dev-cmd/contributions.rb', line 697

def previous_maintainer_reports(from)
  reports = T.let([], T::Array[T::Hash[String, [T::Boolean, T::Boolean]]])
  period_end = Date.iso8601(from)
  (LEAD_ACTIVITY_PERIODS - 1).times do
    period_start = period_end.prev_month(ACTIVITY_PERIOD_MONTHS)
    path = Pathname("brew-contributions-#{period_start.iso8601}-to-#{period_end.iso8601}.csv")
    report = maintainer_activity_report(period_start.iso8601, period_end.iso8601)
    if report.nil?
      if reports.empty?
        opoo "Could not find #{path}; omitting the potential new role column."
      else
        opoo "Could not find #{path}; Lead Maintainer promotion data is incomplete."
      end
      break
    end

    reports << report
    period_end = period_start
  end
  reports
end

#run ⇒ `void`

This method returns an undefined value.

# File 'dev-cmd/contributions.rb', line 114

def run
  maintainer_report_csv = args.maintainer_report_csv
  requested_users = args.user || []
  odie "`--user` must not contain empty values." if requested_users.compact.length != requested_users.length

  odie "Cannot get contributions as `$HOMEBREW_NO_GITHUB_API` is set!" if Homebrew::EnvConfig.no_github_api?
  Utils::GemSetup.install_bundler_gems!(groups: ["contributions"]) if args.csv? || maintainer_report_csv

  if maintainer_report_csv && !args.from && !args.to
    unless maintainer_report_csv.to_s.match?(/\A\d{4}-[1-4]\z/)
      odie "`--maintainer-report-csv` requires YEAR-QUARTER or both `--from` and `--to`."
    end
    quarter_parts = maintainer_report_csv.to_s.split("-")
    from, to = reporting_quarter_dates(quarter_parts.fetch(1).to_i, quarter_parts.fetch(0).to_i)
  else
    if maintainer_report_csv
      if args.from.nil? || args.to.nil?
        odie "`--maintainer-report-csv` requires both `--from` and `--to`."
      end
      if maintainer_report_csv.is_a?(String)
        odie "Use `--maintainer-report-csv` without a value with `--from` and `--to`."
      end
    end
    quarter = args.quarter.presence.to_i
    odie "Value for `--quarter` must be between 1 and 4." if args.quarter.present? && !quarter.between?(1, 4)
    quarter_dates = reporting_quarter_dates(quarter) unless quarter.zero?
    from = args.from.presence || quarter_dates&.first || Date.today.prev_year.iso8601
    to = args.to.presence || quarter_dates&.last || (Date.today + 1).iso8601
  end
  if maintainer_report_csv
    odie "`--from` must precede `--to`." if Date.iso8601(from) >= Date.iso8601(to)
    $stderr.puts "Maintainer report dates: #{from}-to-#{to}"
  elsif args.verbose?
    puts "Date range is #{time_period(from:, to:)}."
  end

  require "utils/github"

  organisation = T.let(nil, T.nilable(String))
  users = if maintainer_report_csv
    []
  elsif (team = args.team.presence)
    team_sections = team.split("/")
    organisation = team_sections.first.presence
    team_name = team_sections.last.presence
    if team_sections.length != 2 || organisation.nil? || team_name.nil?
      odie "Team must be in the format `organisation/team`!"
    end

    puts "Getting members for #{organisation}/#{team_name}..." if args.verbose?
    GitHub.members_by_team(organisation, team_name).keys
  elsif requested_users.present?
    requested_users
  else
    puts "Getting members for Homebrew/maintainers..." if args.verbose?
    GitHub.members_by_team("Homebrew", "maintainers").keys
  end
  user_names = users.to_h { |user| [user, user] }

  repositories = if maintainer_report_csv
    organisation = "Homebrew"
    PRIMARY_REPOS
  elsif (org = organisation.presence) || (org = args.organisation.presence)
    organisation = org
    puts "Getting repositories for #{organisation}..." if args.verbose?
    GitHub.organisation_repositories(organisation, from, to, args.verbose?)
  elsif (repos = args.repositories.presence) && repos.length == 1 && (first_repository = repos.first)
    case first_repository
    when "primary"
      PRIMARY_REPOS
    else
      Array(first_repository)
    end
  elsif (repos = args.repositories.presence)
    organisations = repos.map { |repository| repository.split("/").first }.uniq
    odie "All repositories must be under the same user or organisation!" if organisations.length > 1

    repos
  else
    PRIMARY_REPOS
  end
  organisation ||= repositories.fetch(0).split("/").fetch(0)
  repository_refs = prepare_contribution_repositories(repositories, required: maintainer_report_csv.present?)

  lead_maintainers = T.let({}, T::Hash[String, T::Boolean])
  maintainer_since_dates = T.let({}, T::Hash[String, T.nilable(String)])
  if maintainer_report_csv
    user_names, lead_maintainers, maintainer_since_dates = maintainer_report_users(repository_refs, to)
  end

  results = scan_contributions(
    organisation, repositories, repository_refs, user_names, from:, to:,
    skip_reviews_if_lead_met: maintainer_report_csv.present?,
    progress:                 maintainer_report_csv.present? || args.verbose?
  )
  grand_totals = results.transform_values { |user_results| total(user_results) }

  if maintainer_report_csv
    csv = generate_maintainer_report_csv(
      results, grand_totals, user_names, lead_maintainers, maintainer_since_dates, from, to
    )
    filename = "brew-contributions-#{from}-to-#{to}"
    filename += "-#{user_names.keys.map(&:downcase).sort.join("-")}" if requested_users.present?
    File.write("#{filename}.csv", csv)
    puts csv
    return
  end

  user_names.each_key do |username|
    grand_total = grand_totals.fetch(username)
    greater_than_total = T.let(grand_total.fetch(:merged_pr_author_hit_cap, 0).positive?, T::Boolean)
    contributions = CONTRIBUTION_TYPES.keys.filter_map do |type|
      type_count = grand_total[type]
      next if type_count.nil? || type_count.zero?

      count_prefix = ""
      if ([:merged_pr_author, :merged_pr].include?(type) && grand_total.fetch(:merged_pr_author_hit_cap,
                                                                              0).positive?) ||
         (type == :approved_pr_review && type_count >= MAX_PR_SEARCH) || type_count >= MAX_CONTRIBUTIONS
        greater_than_total ||= true
        count_prefix = ">="
      end

      pretty_type = CONTRIBUTION_TYPES.fetch(type)
      "#{count_prefix}#{Utils.pluralize("time", type_count, include_count: true)} (#{pretty_type})"
    end
    qualifying_total = contribution_count(
      grand_total.slice(*QUALIFYING_CONTRIBUTION_TYPES),
    )
    total = Utils.pluralize("time", qualifying_total, include_count: true)
    total_prefix = ">=" if greater_than_total
    contributions << "#{total_prefix}#{total} (total)"

    contributions_string = [
      "#{username} contributed",
      Utils::Text.to_sentence(contributions),
      "#{time_period(from:, to:)}.",
    ].join(" ")
    if args.csv?
      $stderr.puts contributions_string
    else
      puts contributions_string
    end
  end

  return unless args.csv?

  $stderr.puts
  puts generate_csv(grand_totals)
end

#scan_contributions(organisation, repositories, repository_refs, users, from:, to:, skip_reviews_if_lead_met:, progress:) ⇒ `Hash{String => Hash{String => Hash{Symbol => Integer}}}`

Parameters:

organisation (String)
repositories (Array<String>)
repository_refs (Hash{String => Array<(Pathname, String)>})
users (Hash{String => String})
from (String)
to (String)
skip_reviews_if_lead_met (Boolean)
progress (Boolean)

Returns:

(Hash{String => Hash{String => Hash{Symbol => Integer}}})

# File 'dev-cmd/contributions.rb', line 366

def scan_contributions(organisation, repositories, repository_refs, users, from:, to:,
                       skip_reviews_if_lead_met:, progress:)
  results = users.to_h do |user, _|
    user_results = repositories.to_h do |repository|
      [repository, CONTRIBUTION_TYPES.keys.to_h { |type| [type, 0] }]
    end
    [user, user_results]
  end

  require "utils/github"
  github_users = users.keys.to_h { |user| [user, github_username_for(user, to:)] }
  # Usernames, real names and public emails, so commits under a maintainer's Git identity are matched.
  github_identities = github_users.filter_map do |user, github_user|
    [user, github_identities_for_username(github_user, to:)] if github_user
  end.to_h
  git_authored_pull_requests = users.keys.to_h do |user|
    [user, repositories.to_h { |repository| [repository, Set.new] }]
  end
  git_merged_pull_requests = users.keys.to_h do |user|
    [user, repositories.to_h { |repository| [repository, Set.new] }]
  end
  git_log_format_fields = [
    GIT_LOG_COMMIT_HASH_FORMAT, GIT_LOG_PARENT_HASHES_FORMAT, GIT_LOG_AUTHOR_NAME_FORMAT,
    GIT_LOG_AUTHOR_EMAIL_FORMAT, GIT_LOG_COMMITTER_NAME_FORMAT, GIT_LOG_COMMITTER_EMAIL_FORMAT,
    GIT_LOG_COMMIT_MESSAGE_FORMAT
  ]
  repository_refs.each do |repository, (repository_path, ref)|
    require "utils/git"
    git_log_format = git_log_format_fields.join(GIT_LOG_FIELD_SEPARATOR) + GIT_LOG_RECORD_SEPARATOR
    output = Utils.safe_popen_read(
      Utils::Git.git, "-C", repository_path, "log", ref, "--since=#{from}", "--before=#{to}",
      "--format=#{git_log_format}"
    )
    authored_pull_requests = users.keys.to_h { |user| [user, Set.new] }
    merged_pull_requests = users.keys.to_h { |user| [user, Set.new] }
    parse_git_log(output, users, github_identities:, authored_pull_requests:, merged_pull_requests:)
      .each do |user, counts|
      results.fetch(user)[repository] = counts
      git_authored_pull_requests.fetch(user)[repository] = authored_pull_requests.fetch(user)
      git_merged_pull_requests.fetch(user)[repository] = merged_pull_requests.fetch(user)
    end
  end

  merged_range = "#{from}..#{Date.iso8601(to).prev_day.iso8601}"
  users.each_key do |user|
    github_user = github_users.fetch(user)
    next if github_user.nil?

    merged_pull_requests = cached_github_request(Array, "merged-at", organisation, github_user, merged_range,
                                                 to:) do
      GitHub.search_issues("", is: "merged", user: organisation, author: github_user, merged: merged_range)
    rescue GitHub::API::ValidationFailedError
      opoo "Couldn't search GitHub for PRs authored by #{github_user}. Their profile might be private. " \
           "Defaulting to 0."
      []
    end
    capped_merged_pull_requests = merged_pull_requests.length >= MAX_PR_SEARCH
    if capped_merged_pull_requests
      results.fetch(user).fetch(repositories.fetch(0))[:merged_pr_author_hit_cap] =
        1
    end
    merged_pull_requests.each do |pull_request|
      repository = pull_request.fetch("repository_url").delete_prefix("#{GitHub::API_URL}/repos/")
      next unless repositories.include?(repository)

      authored_pull_requests = git_authored_pull_requests.fetch(user).fetch(repository)
      merged_pull_request_ids = git_merged_pull_requests.fetch(user).fetch(repository)
      add_merged_pull_request_id(pull_request, authored_pull_requests, merged_pull_request_ids)
    end
    repositories.each do |repository|
      counts = results.fetch(user).fetch(repository)
      authored_pull_requests = git_authored_pull_requests.fetch(user).fetch(repository)
      merged_pull_request_ids = git_merged_pull_requests.fetch(user).fetch(repository)
      update_merged_pull_request_counts(counts, authored_pull_requests, merged_pull_request_ids)
    end
    next unless skip_reviews_if_lead_met
    next unless capped_merged_pull_requests
    next if lead_activity_met?(results.fetch(user))

    repositories.each do |repository|
      break if lead_activity_met?(results.fetch(user))

      repository_counts = results.fetch(user).fetch(repository)
      repository_total = contribution_count(repository_counts.slice(*QUALIFYING_CONTRIBUTION_TYPES))
      qualifying_total = contribution_count(total(results.fetch(user)).slice(*QUALIFYING_CONTRIBUTION_TYPES))
      next if repository_total >= LEAD_REPOSITORY_ACTIVITY_THRESHOLD &&
              qualifying_total >= MAINTAINER_ACTIVITY_THRESHOLD

      $stderr.puts "Querying merged-PR search for #{user} in #{repository}..." if progress
      repository_pull_requests = cached_github_request(Array, "merged-at", repository, github_user,
                                                       merged_range, to:) do
        GitHub.search_issues("", is: "merged", repo: repository, author: github_user, merged: merged_range)
      end
      authored_pull_requests = git_authored_pull_requests.fetch(user).fetch(repository)
      merged_pull_request_ids = git_merged_pull_requests.fetch(user).fetch(repository)
      repository_pull_requests.each do |pull_request|
        add_merged_pull_request_id(pull_request, authored_pull_requests, merged_pull_request_ids)
      end
      update_merged_pull_request_counts(repository_counts, authored_pull_requests, merged_pull_request_ids)
    end
  end

  review_users = github_users.filter_map { |user, github_user| [user, github_user] if github_user }
  review_users.reject! { |user, _| lead_activity_met?(results.fetch(user)) } if skip_reviews_if_lead_met
  approved_to = Date.iso8601(to).prev_day.iso8601
  review_users.each_with_index do |(user, github_user), index|
    if progress
      $stderr.puts "Querying approved-review search for #{user} (#{index + 1}/#{review_users.length})..."
    end
    approved_reviews = cached_github_request(Array, "approved", organisation, github_user, from, approved_to,
                                             to:) do
      GitHub.search_approved_pull_requests_in_user_or_organisation(organisation, github_user,
                                                                   from:, to: approved_to)
    end
    capped_reviews = approved_reviews.length >= MAX_PR_SEARCH
    results.fetch(user).fetch(repositories.fetch(0))[:approved_pr_review_hit_cap] = 1 if capped_reviews
    approved_reviews.each do |pull_request|
      repository = pull_request.fetch("repository_url").delete_prefix("#{GitHub::API_URL}/repos/")
      next unless repositories.include?(repository)

      increment_contribution_count(results.fetch(user).fetch(repository), :approved_pr_review)
    end
    next unless skip_reviews_if_lead_met
    next unless capped_reviews
    next if lead_activity_met?(results.fetch(user))

    repositories.each do |repository|
      break if lead_activity_met?(results.fetch(user))

      repository_counts = results.fetch(user).fetch(repository)
      repository_total = contribution_count(repository_counts.slice(*QUALIFYING_CONTRIBUTION_TYPES))
      qualifying_total = contribution_count(total(results.fetch(user)).slice(*QUALIFYING_CONTRIBUTION_TYPES))
      next if repository_total >= LEAD_REPOSITORY_ACTIVITY_THRESHOLD &&
              qualifying_total >= MAINTAINER_ACTIVITY_THRESHOLD

      $stderr.puts "Querying approved-review search for #{user} in #{repository}..." if progress
      repository_reviews = cached_github_request(Array, "approved", repository, github_user,
                                                 from, approved_to, to:) do
        GitHub.search_issues("", is: "pr", review: "approved", repo: repository, reviewed_by: github_user,
                             from:, to: approved_to)
      end
      repository_counts[:approved_pr_review] = repository_reviews.length
    end
  end

  results
end

Class: Homebrew::DevCmd::Contributions Private

Defined Under Namespace

Constant Summary collapse

Instance Method Summary collapse

Methods included from SystemCommand::Mixin

Methods inherited from AbstractCommand

Methods included from Utils::Output::Mixin

Constructor Details

Instance Method Details

#args ⇒ Homebrew::DevCmd::Contributions::Args

#cached_github_request(type, *key_parts, to:, &block) ⇒ T.type_parameter(:U)

#github_identities_for_username(username, to:) ⇒ Array<String>

#github_username_for(user, to:) ⇒ String?

#maintainer_activity_report(from, to, current_report: nil) ⇒ Hash{String => Array<(Boolean, Boolean)>}?

#maintainer_report_users(repository_refs, to) ⇒ Array<(Hash{String => String}, Hash{String => Boolean}, Hash{String => String, nil})>

#maintainer_since(repository_path, ref, user, name) ⇒ String?

#parse_git_log(output, users, github_identities: nil, authored_pull_requests: nil, merged_pull_requests: nil) ⇒ Hash{String => Hash{Symbol => Integer}}

#potential_maintainer_role(user, role, maintainer_since_date, period_end, activity, previous_reports) ⇒ String?

#previous_maintainer_reports(from) ⇒ Array<Hash{String => Array<(Boolean, Boolean)>}>

#run ⇒ void

#scan_contributions(organisation, repositories, repository_refs, users, from:, to:, skip_reviews_if_lead_met:, progress:) ⇒ Hash{String => Hash{String => Hash{Symbol => Integer}}}

#args ⇒ `Homebrew::DevCmd::Contributions::Args`

#cached_github_request(type, *key_parts, to:, &block) ⇒ `T.type_parameter(:U)`

#github_identities_for_username(username, to:) ⇒ `Array<String>`

#github_username_for(user, to:) ⇒ `String`^?

#maintainer_activity_report(from, to, current_report: nil) ⇒ `Hash{String => Array<(Boolean, Boolean)>}`^?

#maintainer_report_users(repository_refs, to) ⇒ `Array<(Hash{String => String}, Hash{String => Boolean}, Hash{String => String, nil})>`

#maintainer_since(repository_path, ref, user, name) ⇒ `String`^?

#parse_git_log(output, users, github_identities: nil, authored_pull_requests: nil, merged_pull_requests: nil) ⇒ `Hash{String => Hash{Symbol => Integer}}`

#potential_maintainer_role(user, role, maintainer_since_date, period_end, activity, previous_reports) ⇒ `String`^?

#previous_maintainer_reports(from) ⇒ `Array<Hash{String => Array<(Boolean, Boolean)>}>`

#run ⇒ `void`

#scan_contributions(organisation, repositories, repository_refs, users, from:, to:, skip_reviews_if_lead_met:, progress:) ⇒ `Hash{String => Hash{String => Hash{Symbol => Integer}}}`