Skip to content

ci: check the CLI and API references against the code - #242

Merged
afonsojramos merged 6 commits into
v3from
ci/reference-checks
Oct 1, 2026
Merged

afonsojramos merged 6 commits into
v3from
ci/reference-checks

Conversation

@afonsojramos

Copy link
Copy Markdown
Member

Summary

The v3 docs pass (#241) found the reference pages had drifted from the CLI and the wrapper in many places. Two checks now catch that automatically, on every pull request and weekly (so a CLI change that outdates the docs shows up without a docs PR).

  • CLI commands (pnpm run check:cli-commands <spicetify>): runs spicetify --help and each subcommand's --help recursively from the newest v3 release (Linux x86_64 asset, checksum verified), and compares the command paths with cli/commands.md (single-code-span headings, and spicetify ... lines in shell code blocks). Fails on commands missing from the page and on documented commands the CLI doesn't have. The Linux-only spotify commands only warn on a non-Linux binary.
  • API wrapper (pnpm run check:api-wrapper): lists the top-level members of declare namespace Spicetify in the CLI's v3-beta globals.d.ts with the TypeScript compiler API, and checks each has a page (by title), a `Spicetify.X` heading, or a row in the libraries table under development/api-wrapper. Fails on undocumented members and on pages for members that no longer exist. @deprecated and underscore members are skipped; the allowlist is just the test debug helper.
  • .github/workflows/reference-checks.yml: both checks on pull_request, weekly, and on dispatch, with contents: read only and actions pinned by SHA.
  • New reference pages for the members the check found undocumented: Color, Locale, extractColorPreset, Events, and a ContextMenuV2 section. (Config, the last gap, is now @deprecated in the CLI, fix(types): mark Config deprecated, since v3 never sets it cli#3998.)

Testing

  • Both checks pass locally (CLI against the rc.1 binary, 31 commands on macOS; the Linux spotify subtree checked with a stub). pnpm build passes with 0 broken links.
  • Each check fails on deliberate drift: a fake command, a removed ### restart section, a bogus documented command; a deleted Queue page, a CORSProxy heading turned into prose, a page for a member that doesn't exist.
  • The workflow itself first runs on this PR; check the cli-commands job's release download and the GITHUB_TOKEN Permissions header.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying spicetify-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: ae497a6
Status: ✅  Deploy successful!
Preview URL: https://97617349.spicetify-docs.pages.dev
Branch Preview URL: https://ci-reference-checks.spicetify-docs.pages.dev

View logs

@afonsojramos
afonsojramos merged commit e3ba512 into v3 Oct 1, 2026
4 checks passed
@afonsojramos
afonsojramos deleted the ci/reference-checks branch October 1, 2026 14:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant