test-bot: shard dependent testing across CI matrix runners

[GunniBusch]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) with your changes locally?

---

• AI was used to generate or assist with generating this PR. Please specify below how you used AI to help you, and what steps you have taken to manually verify the changes.

---

This implements a way to parallelise dependency testing using shards. This was inspired by how bazel does it. This implements the idea of Homebrew/homebrew-core#206400. But it does not resolve this issue because my feature is not the default behaviour meaning, one merged (or working), I will open a pr in core.

Meanwhile during developing, I made a testing repo to test if this is working.

The latest run is: https://github.com/GunniBusch/brew-dependent-shard-e2e/actions/runs/22170548663

Summary

This PR adds deterministic dependent-test sharding to brew test-bot, with dynamic shard sizing in determine-test-runners, and wires shard metadata into runner matrix rows.

What changed

• Added brew determine-test-runners flags:
  • --dependent-shard-max-runners=<n>
  • --dependent-shard-min-dependents-per-runner=<n>
• Added brew test-bot flags:
  • --dependent-shard-count=<m>
  • --dependent-shard-index=<n>
• Added validation for flag combinations and ranges in command layer.
• Added DependentShardMatrix to expand dependent matrix rows per active runner and compute shard counts from dependent cardinality.
• Updated GitHubRunnerMatrix to delegate dependent row expansion and include:
  • dependent_shard_count
  • dependent_shard_index
• Added DependentShardAssigner for deterministic shard assignment in dependent testing.
• Updated FormulaeDependents to shard the final runnable dependent set (after existing filtering/defer logic) via the assigner.
• Added bounded shard capacity in assignment to prevent pathological “one shard gets almost everything” behavior when dependency overlap is high.
• Kept non-dependent matrix behavior unchanged.
• CI fix in tests.yml: syntax job now installs shellcheck/shfmt directly instead of restoring cached Homebrew prefix, to avoid stale repo content overriding PR checkout.

Behavioral notes

• Backward compatible: if shard flags are not used (or shard count is 4), behavior is changed but not breaking
• Assignment is deterministic for identical inputs (same graph + same shard params).

Test coverage

• CLI validation specs for both commands.
• Matrix expansion/count/clamp specs.
• Dependent sharding specs for determinism, disjointness, completeness, object/name inputs, locality behavior, and balance guard.

[Copilot]

Pull request overview

This PR adds deterministic sharding for brew test-bot’s “formulae dependents” testing and updates the GitHub Actions runner matrix generation so dependent testing can be split across multiple CI jobs per runner.

Changes:

• Introduces DependentShardAssigner (deterministic assignment) and applies it in FormulaeDependents to shard the final runnable dependent set.
• Adds DependentShardMatrix and wires dependent shard metadata (dependent_shard_count, dependent_shard_index) into GitHubRunnerMatrix rows, with sizing controls exposed via determine-test-runners.
• Adds CLI validations + specs, and updates CI workflow steps to avoid restoring a cached prefix in jobs where it can overwrite the PR checkout.

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Library/Homebrew/test_bot/formulae_dependents.rb	Builds dependency “feature” sets and filters dependents based on the shard assignment.
Library/Homebrew/test_bot/dependent_shard_assigner.rb	Implements deterministic dependent→shard assignment with locality/balance heuristics.
Library/Homebrew/test/test_bot/formulae_dependents_spec.rb	Specs for FormulaeDependents sharding behavior (determinism/disjointness/etc.).
Library/Homebrew/test/test_bot/dependent_shard_assigner_spec.rb	Specs covering assigner determinism, locality, balance, and argument validation.
Library/Homebrew/test/github_runner_matrix_spec.rb	Specs for dependent matrix row expansion/clamping and non-dependent behavior.
Library/Homebrew/test/dev-cmd/test-bot_spec.rb	Integration specs for test-bot dependent shard flag validation.
Library/Homebrew/test/dev-cmd/determine-test-runners_spec.rb	Integration specs for determine-test-runners new shard sizing flags.
Library/Homebrew/test/dependent_shard_matrix_spec.rb	Unit specs for shard row expansion and validation in DependentShardMatrix.
Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/determine_test_runners.rbi	Adds RBI accessors for new determine-test-runners args.
Library/Homebrew/sorbet/rbi/dsl/homebrew/cmd/test_bot_cmd.rbi	Adds RBI accessors for new test-bot shard args.
Library/Homebrew/github_runner_matrix.rb	Adds dependent shard defaults, computes per-runner dependent counts, and expands matrix rows via DependentShardMatrix.
Library/Homebrew/dev-cmd/test-bot.rb	Adds dependent sharding flags and validates shard argument combinations/ranges.
Library/Homebrew/dev-cmd/determine-test-runners.rb	Adds shard sizing flags and parsing/validation; passes values into GitHubRunnerMatrix.
Library/Homebrew/dependent_shard_matrix.rb	New helper to expand dependent runner spec rows by computed shard count per runner.
.github/workflows/tests.yml	Avoids restoring cached Homebrew prefix in jobs where it can override the PR checkout; installs tools directly.

Files not reviewed (2)

• Library/Homebrew/sorbet/rbi/dsl/homebrew/cmd/test_bot_cmd.rbi: Language not supported
• Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/determine_test_runners.rbi: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.