[lil-lon]

Problem

mise bootstrap packages apply reports formulae like brew:zip / brew:unzip
as installed on Linux, but their commands never appear in <prefix>/bin. The
kegs are poured, yet no symlinks are created because the formulae are marked
keg-only — even though these formulae are keg-only only because macOS already
provides them, and brew itself links them normally on Linux.

Cause

mise deserializes only the keg_only bool from the formulae.brew.sh JSON and
ignores the adjacent keg_only_reason object. link_keg then skips prefix
linking whenever the bool is true, with no OS or reason check. Homebrew's own
KegOnlyReason#applicable? returns false outside macOS for the
:provided_by_macos / :shadowed_by_macos reasons, so brew links these
formulae on Linux while mise does not.

Change

• Parse keg_only_reason and add Formula::keg_only_for_target(), mirroring
  brew's KegOnlyReason#applicable?: macOS-tied reasons do not apply on other
  OSes; :versioned_formula, free-text reasons, and a missing reason stay
  keg-only everywhere.
• Use it at both link_keg call sites (bottle pour and source build).
  link_keg itself is unchanged; the policy decision moves to the callers.
• The tap-formula DSL shim now captures the keg_only reason and emits it in
  the same shape as the API JSON, so tapped formulae behave the same way.
• Docs: note the platform-dependent keg-only behavior.

macOS behavior is unchanged by construction.

Tests

• Unit tests for the applicability rules (macOS-tied reasons vs. others).
• The tap metadata test now asserts the extracted reason.
• e2e (test_system_install_brew_linux): brew:unzip ends up with
  <prefix>/bin/unzip linked, no .mise-keg-only marker, and a runnable
  binary.

Verification

Passing locally:

• cargo test --all-features system::packages::brew
• mise run lint
• cargo clippy --workspace --all-features --all-targets -- -D warnings

Known limitation

Kegs already installed by earlier mise versions keep their .mise-keg-only
marker and stay unlinked; the repair path intentionally does not consult
formula metadata. They are fixed by the next formula version bump via
mise bootstrap packages upgrade, or by removing the keg and re-running
mise bootstrap packages apply.

AI-assisted — Tool: Claude Code; model: anthropic/claude-fable-5; version: unavailable.

Summary by CodeRabbit

• New Features

  • Homebrew formula handling now accounts for platform-specific keg-only rules.
  • macOS-specific keg-only formulae are linked normally on Linux and other applicable platforms.
  • Formula metadata now records keg-only reasons for more accurate installation behavior.

• Bug Fixes

  • Linux installations correctly link and run formulae that are only keg-only on macOS.

• Documentation

  • Clarified platform-specific keg-only behavior in the Homebrew documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Advanced

Run ID: 7e4ff34a-9c40-4422-aaa5-a158a05c92b3

📥 Commits

Reviewing files that changed from the base of the PR and between a3304cd and 3ede283.

📒 Files selected for processing (7)

• docs/bootstrap/packages/brew.md
• e2e/cli/test_system_install_brew_linux
• src/system/packages/brew/api.rs
• src/system/packages/brew/pour.rs
• src/system/packages/brew/source.rs
• src/system/packages/brew/tap.rs
• src/system/packages/brew/tap_formula_metadata.rb

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Homebrew metadata now records keg-only reasons. Linking evaluates those reasons for the target platform, including normal Linux linking for macOS-provided formulae. Tests and documentation cover the new behavior.

Changes

Homebrew keg-only linking

Layer / File(s)	Summary
Capture keg-only reasons src/system/packages/brew/tap_formula_metadata.rb, src/system/packages/brew/api.rs	Formula metadata records and deserializes optional keg-only reasons.
Apply target-specific keg status src/system/packages/brew/api.rs, src/system/packages/brew/pour.rs, src/system/packages/brew/source.rs	macOS-specific reasons apply only on macOS. Pour and source linking use the target-specific keg-only status.
Validate Linux linking behavior src/system/packages/brew/api.rs, src/system/packages/brew/tap.rs, e2e/cli/test_system_install_brew_linux, docs/bootstrap/packages/brew.md	Tests and documentation cover metadata extraction, platform-specific reasons, and normal Linux linking for unzip.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: jdx

Sequence Diagram(s)

sequenceDiagram
  participant FormulaMetadata
  participant Formula
  participant pour
  participant link_keg
  FormulaMetadata->>Formula: deserialize keg_only_reason
  Formula->>Formula: keg_only_for_target()
  Formula-->>pour: target-specific keg-only status
  pour->>link_keg: link keg with status

Loading

Merge Risk: ⚪ Minimal · up to 3ede2

The platform-aware keg-only behavior is applied consistently to both installation paths and is covered for Linux linking, with no concrete unresolved merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 47.37% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 5 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: linking formulae that are keg-only on macOS but should be linked on Linux.

Full details: Docstring Coverage

Explanation

Docstring coverage is 47.37% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 5 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with consistent policy application across both installation paths and focused regression coverage.

Summary

• Applies the target-aware policy to bottle and source installations.
• Captures equivalent metadata when evaluating tapped formulae.
• Adds unit, tap-metadata, and Linux end-to-end coverage.
• Documents the platform-dependent linking behavior.

_{Reviews (1) · Last reviewed commit: "Merge branch 'main' into fix/brew-keg-on..."}