• 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 style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

Overview

This PR enhances TapAuditor to provide comprehensive validation for formula_renames.json and cask_renames.json files in taps, and updates the rename documentation.

Changes

New Validation Checks (tap_auditor.rb)

The new check_renames method validates rename entries and detects:

1. Invalid format: .rb file extensions in rename keys or values (should use tokens only)
2. Missing targets: Rename targets that don't exist in the tap
3. Chained renames: Detects rename chains (A → B → C → D) and suggests collapsing them to the final target (A → D). Includes cycle detection to prevent infinite loops.
4. Name conflicts: Old names that conflict with existing formulae/casks in the tap

Implementation Details

• Added cask_renames to attr_reader (was missing)
• Replaced simple check_formula_list call for formula_renames.json with check_renames method
• Added check_renames call for cask_renames.json validation
• Chained rename detection follows chains to their final target with cycle detection
• Implemented comprehensive test coverage for all validation scenarios

Documentation Updates (docs/Rename-A-Formula.md)

• Added missing cask rename process documentation
• Added "Important Rules" section documenting all validation requirements
• Updated title to "Renaming a Formula or Cask" to reflect complete coverage
• Provided clear examples for both formula and cask renames

Motivation

This was motivated by Homebrew/homebrew-cask#235881, which fixes an incorrect cask_renames.json entry that erroneously included a .rb file extension in the old cask name. This caused Homebrew to fail to properly migrate users from multiviewer-for-f1 to multiviewer, breaking the rename functionality entirely.

Currently, there's no validation to catch these errors before they're merged, meaning broken renames can silently break user upgrades. This PR adds auditing to prevent such issues:

• Invalid extensions: Catches .rb extensions that break rename matching
• Chained renames: Detects and suggests collapsing multi-level chains (A → B → C → D becomes A → D)
• Missing targets: Ensures renames point to formulae/casks that actually exist
• Name conflicts: Warns when old names conflict with existing formulae/casks

These checks will catch issues during brew audit before they're merged and affect users.

Testing

All new functionality is covered by RSpec tests in tap_auditor_spec.rb:

• Tests for cask rename validation (7 test cases, including multi-level chain detection)
• Tests for formula rename validation (3 test cases)
• All tests passing locally

Local validation:

✓ brew style (No offenses)
✓ brew typecheck (No errors)
✓ brew tests --only=tap_auditor (All 10 tests passing)