Add scoped install step warnings (11/24)

[MikeMcQuaid]

Some formula hooks only warn when a persistent path needs user attention
and do not need arbitrary post-install code.

• add a literal warning step shared with cask flight phases
• compose warnings with path guards instead of embedded conditions
• expand fixed context tokens in warning messages

AI disclosure: using OpenAI Codex 5.6 Sol max with local review and
testing.

[Copilot]

Pull request overview

Adds a first-class warn install-step to Homebrew’s InstallSteps DSL, enabling scoped warnings (via path guards like if_path_exists) without requiring arbitrary Ruby in post_install hooks. This supports incremental conversion of formula/cask hooks into declarative install steps while keeping warning messages token-expandable at runtime.

Changes:

• Add warn to Homebrew::InstallSteps::DSL and execute it in the runner via opoo with template-token expansion.
• Update RuboCop install-steps allowlist/specs to recognise warn as a valid step.
• Add a runner spec validating that warn executes when an if_path_exists guard matches.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Library/Homebrew/install_steps.rb	Introduces warn step in the DSL and runner execution.
Library/Homebrew/rubocops/shared/install_steps_helper.rb	Extends allowed step method list to include warn (formula allowlist only).
Library/Homebrew/test/install_steps_spec.rb	Adds spec covering warn under a matching path scope.
Library/Homebrew/test/rubocops/install_steps_spec.rb	Updates RuboCop spec expectations to include warn in the allowed methods list.
docs/Formula-Cookbook.md	Updates cookbook command/lifecycle section to reference warning-related steps (currently mismatched with implementation).

Comments suppressed due to low confidence (2)

Library/Homebrew/rubocops/shared/install_steps_helper.rb:31

• warn is added to ALLOWED_STEP_METHODS but not to CASK_ALLOWED_STEP_METHODS, so the cask install-steps cop will still flag warn as an invalid step in cask flight-phase *_steps blocks (and its error message won’t mention it). Add *NOTICE_STEP_METHODS to the cask allowlist to keep formula and cask step DSL parity.

      CASK_ALLOWED_STEP_METHODS = T.let(
        [*FILE_PREPARATION_STEP_METHODS, *CONFIG_WRITE_STEP_METHODS, *KEYCHAIN_STEP_METHODS,
         *PERMISSION_STEP_METHODS, *COMMAND_STEP_METHODS, *STEP_SCOPE_METHODS].freeze,
        T::Array[Symbol],
      )

docs/Formula-Cookbook.md:1111

• This sentence documents warn_if_exists, which doesn’t exist. Consider describing warn and mention that it can be wrapped in if_path_exists/unless_path_exists guards to make it conditional on paths.

`terminate_process` terminates a process by name or, with `matching: :full`, by its full command line. It supports retries, `notices:` shown before the first attempt and a `failure_message:` warning. `warn_if_exists` emits a warning when any listed path exists.

---

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