audit: add --fix command for casks

[bevanjkay]

This PR introduces a --fix flag for brew audit, with the goal being to correct some common cask audit failures, to use with brew bump. This will reduce maintainer workload, and could be extended to additional corrections that occur regularly.

Automatic corrections can be applied for issues with;

1. depends_on macos:
2. Incorrect artifact stanza case.
3. The deprecated verified parameter automatically removed from urls.

Corrected problems are reported as corrected rather than failing the audit (matching brew style --fix), and are excluded from GitHub Actions annotations. If a rewrite produces a cask that no longer loads, the original file is restored.

Note: brew bump-cask-pr passes --fix by default. So brew bump will automatically fix these issues. This matches the existing behaviour of the brew style checks within this process.

---

• 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.

---

I used claude-code with Opus 5 to create the changes.

[Copilot]

Pull request overview

Adds brew audit --fix support for casks to automatically correct a small set of common audit failures (to reduce maintainer workload and improve brew bump flows), and updates user-facing docs/completions accordingly.

Changes:

• Extend brew audit --fix so cask audits can auto-correct: depends_on macos: minimums, artifact stanza case mismatches, and deprecated url ... verified: usage.
• Add AST helpers + specs to support the cask rewrites, and extend cask audit specs to validate “corrected” behavior and rollback on invalid rewrites.
• Make bump-cask-pr run cask audit with --fix and add documentation/manpage/completions text describing the expanded behavior.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
manpages/brew.1	Documents audit --fix behavior for casks in the generated manpage.
Library/Homebrew/utils/ast.rb	Adds CaskAST rewrite helpers for removing hash pairs and updating/inserting depends_on macos: stanzas.
Library/Homebrew/test/utils/ast/cask_ast_spec.rb	Adds unit specs for the new CaskAST rewrite helpers.
Library/Homebrew/test/cask/audit_spec.rb	Adds coverage for cask audit auto-fixes + rollback behavior.
Library/Homebrew/dev-cmd/bump-cask-pr.rb	Runs cask audit with --fix and adds a dedicated min_os fix pass for autobump bot flows.
Library/Homebrew/dev-cmd/audit.rb	Adds audit_fix plumbing, treats “all problems corrected” as success, and suppresses corrected issues in GHA annotations.
Library/Homebrew/cask/auditor.rb	Plumbs the audit_fix option through to Cask::Audit.
Library/Homebrew/cask/audit.rb	Implements fix-capable paths for verified, artifact case, and min_os audits, and marks corrected problems.
docs/Manpage.md	Updates the manpage documentation source for audit --fix.
completions/zsh/_brew	Updates audit --fix completion help text.
completions/fish/brew.fish	Updates audit --fix completion help text.

---

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

[MikeMcQuaid]

IMO particularly if we're using ASTs: I think it makes more sense to move these checks into RuboCops to be fixed with brew style --fix rather than adding brew audit --fix. Most audits can't be fixed automatically. Thoughts?

[bevanjkay]

I did think about this, and is part of the reason I opened this tentatively as a draft for now, to discuss implementation.

As far as I can see, nothing in the Rubocop side runs any "package-level" checks, so there's no integration with archive extraction etc.. This is required to resolve the issues that are being fixed here.

The alternative option to consider would be Rubocop checks that sit behind a separate flag, but at the moment there's not "style" checks that require network access at all, so it would double up on extraction and work that is being complete in audit. Otherwise, a way of integrating the style and audit checks together might be able to handle this better.

--

Just one clarification, the verified fix doesn't belong here, it should be a rubocop.