Add brew tests --load-only and break the install require cycle

[p-linnane]

brew tests emits a Ruby 4 circular require warning while loading the specs: loading in progress, circular require considered harmful - Library/Homebrew/install.rb. It was suppressed with Warnings.ignore wrappers in four spec files, which hid the warning without removing the cycle.

The cycle is install -> upgrade -> reinstall -> extend/os/reinstall -> extend/os/mac/reinstall -> install. Homebrew::Install is only used on the branch that reinstalls pkgconf after a macOS SDK mismatch, so deferring the require into reinstall_pkgconf_if_needed! breaks the cycle and lets the four suppressions go.

Warnings.fail_on raises on a matching warning and spec_helper registers the circular-require pattern, so a new cycle fails the suite instead of scrolling past. An explicit Warnings.ignore still takes precedence, and fail_on also accepts a block for thread-scoped use.

brew tests --load-only loads every selected spec in its own RSpec process without running examples, which is what surfaces this class of cycle. It reuses the command's existing OS filtering and selection. The macOS and Linux jobs run it last, so a timeout can only truncate the supplemental check, and .rspec_parallel skips the runtime log, JUnit and GitHub formatters on dry runs.

Reproduce on main:

./bin/brew ruby -e '$VERBOSE = true; require "install"'

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include brew benchmark results.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• I did not use AI/LLM to create this PR, or I disclosed the tool/model below and reviewed its output; I did not attribute commits to AI and will answer maintainer questions and review comments myself without AI/LLM.

Claude Code (Opus 5) drafted the implementation and tests; I reviewed the diff, verified the warning reproduces before the change and is absent after, and ran brew lgtm --online plus targeted specs on macOS and Linux.

---

[Copilot]

Pull request overview

This pull request strengthens Homebrew’s test harness by making circular-require warnings fail fast and by adding a new brew tests --load-only mode to load specs in isolation, while also eliminating an existing install-related require cycle on macOS.

Changes:

• Add brew tests --load-only to load selected spec files independently (via per-file RSpec processes) without running examples.
• Introduce Warnings.fail_on and register circular-require warnings as fatal in the RSpec spec_helper, replacing prior per-spec suppression.
• Break the install/reinstall require cycle by deferring require "install" to the specific macOS pkgconf mismatch branch.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
manpages/brew.1	Documents the new --load-only option for brew tests.
Library/Homebrew/warnings.rb	Adds fatal-warning support via Warnings.fail_on and enforces it inside the Warning.warn hook.
Library/Homebrew/test/warnings_spec.rb	Adds unit tests covering fatal-warning behavior and scoping/restoration semantics.
Library/Homebrew/test/spec_helper.rb	Makes circular-require warnings fatal for the test suite by default.
Library/Homebrew/test/os/mac/reinstall_spec.rb	Updates macOS reinstall specs to explicitly require "install" now that it’s deferred in implementation.
Library/Homebrew/test/formula_installer_spec.rb	Removes circular-require suppression wrapper around require "install".
Library/Homebrew/test/dev-cmd/tests_spec.rb	Adds coverage for brew tests --load-only argument construction and line-qualified behavior.
Library/Homebrew/test/cmd/shared_examples/reinstall_pkgconf_if_needed.rb	Ensures shared examples explicitly require "install" where Homebrew::Install is referenced.
Library/Homebrew/test/cmd/install_spec.rb	Removes circular-require suppression wrapper around require "install".
Library/Homebrew/test/cask/installer_spec.rb	Removes circular-require suppression wrapper around require "install".
Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/tests.rbi	Adds Sorbet RBI for the new load_only? argument helper.
Library/Homebrew/extend/os/mac/reinstall.rb	Defers require "install" into reinstall_pkgconf_if_needed! to break the cycle.
Library/Homebrew/dev-cmd/tests.rb	Implements --load-only (dry-run + per-file process loading) in the brew tests dev command.
Library/Homebrew/.rspec_parallel	Skips runtime/JUnit/GitHub formatters on --dry-run to keep load-only runs lightweight.
docs/Manpage.md	Documents the new --load-only option in the manpage source.
completions/zsh/_brew	Adds --load-only completion/help text for zsh.
completions/fish/brew.fish	Adds --load-only completion/help text for fish.
completions/bash/brew	Adds --load-only completion for bash.
.github/workflows/tests.yml	Adds a CI step to run brew tests --load-only on Linux and macOS jobs.

Files not reviewed (1)

• Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/tests.rbi: File type not supported

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[MikeMcQuaid]

Thanks, nice idea! Just want to tweak when it's run.

[MikeMcQuaid]

Thanks!