ci(docs): validate documented Homebrew packages - #362
Merged
Conversation
Signed-off-by: hanthor <hanthor@users.noreply.github.com>
… check The checker flagged three true positives that were missing the `# no-verify:` escape hatch: - docs/bluefin-cli/index.md had two `brew install bluefin-cli` blocks; only the second was annotated, and the checker dedupes by package name with first-seen-wins, so the tuna-os/tap block still failed. - docs/homebrew-tap/index.md installs corral-vm and tavern, both published to tuna-os/tap rather than homebrew-core. All three 404 on the Homebrew formula and cask APIs, and each is documented directly under a `brew tap tuna-os/tap` line, so the escape hatch is the correct resolution rather than a doc fix. Assisted-by: Claude Code
This was referenced Sep 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Supersedes #358 (same change plus the CI fix below; the original PR head lives on a fork this session cannot push to).
Closes #347.
Adds a registry-backed check for Homebrew packages used in fenced documentation commands. Formula and cask names are verified against the Homebrew API; definitive 404s fail the check, while registry outages warn and remain non-blocking. Supports an explicit
# no-verify: reasonescape hatch for packages published outside homebrew-core, runs in the docs lint workflow, and is available viajust check-install-commands/npm run check-install-commands.What this adds over #358
#358's own CI failed (
Node.js Syntax & Tests) because the checker found three real unannotated tap-only packages:bluefin-clidocs/bluefin-cli/index.mdcorral-vmdocs/homebrew-tap/index.mdtaverndocs/homebrew-tap/index.mddocs/bluefin-cli/index.mdhas twobrew install bluefin-cliblocks and #358 annotated only the second. The checker dedupes by package name with first-seen-wins, so the earlierbrew tap tuna-os/tapblock still failed the run.docs/homebrew-tap/index.mdwas never annotated at all.All three are published to
tuna-os/tapand appear directly under abrew tap tuna-os/tapline, so the# no-verify:escape hatch is the correct resolution — not a doc change. Verified each against the live formula and cask APIs rather than trusting the doc.Validation
node scripts/check-install-commands.test.mjs— OKnode scripts/check-install-commands.mjsover the whole docs tree — exit 0, no missing packagesmain(clean); the merge pulled indocs/homebrew-tap/index.md, which is where two of the three findings live