Skip to content

Skip hidden commands in breaking change detection - #8463

Closed
nickwesselman wants to merge 1 commit into
mainfrom
nick/major-change-check-skip-hidden
Closed

Skip hidden commands in breaking change detection#8463
nickwesselman wants to merge 1 commit into
mainfrom
nick/major-change-check-skip-hidden

Conversation

@nickwesselman

Copy link
Copy Markdown
Contributor

WHY are these changes introduced?

The breaking change check treats every command in packages/cli/oclif.manifest.json as
public surface. extractManifestSurface never reads a command's hidden field, so
renaming a flag on a hidden command fails Breaking change detection even though nothing
users can discover has changed.

CONTRIBUTING.md scopes the stable Command surface to what the CLI exposes; a command
marked static hidden = true isn't part of it. The check is currently stricter than the
written policy.

This surfaced on #8459, which renames --with-demo-data to --demo-data on
store store create dev — a hidden command whose flag only reached main alongside
unreleased work. The check reported a removed flag and a removed env var and failed the PR.

WHAT is this pull request doing?

Skips hidden commands when building the manifest surface:

if (cmd.hidden) continue

Because removedCommands, removedFlags and removedEnvVars all derive from that
surface, one guard covers all three scans.

Two deliberate details:

  • hidden is read from each manifest independently, not unioned across baseline and
    current. A command that was visible in the baseline and is hidden now still reports as a
    removed command. That keeps the obvious loophole closed — a PR can't hide a command and
    strip its flags in the same change without being flagged — and it errs the way the rest
    of this file already errs, "widening rather than silently skipping potential removals."
  • An env var shared with a visible command stays tracked through that command, so
    removing it there is still reported.

extractManifestSurface is now exported so it can be tested directly.

How to test your changes?

node --test workspace/src/major-change-check.test.js — 20 tests pass, including four new
ones covering hidden-command omission, env vars used only by hidden commands, env vars
shared with a visible command, and the per-manifest hidden reading.

I also ran the extractor against the real manifests to confirm both directions:

  • main vs Ask about demo data when creating a dev store interactively #8459's branch (the hidden-command flag rename) → removedCommands: [],
    removedFlags: [], removedEnvVars: [], so the check passes.
  • main with a flag deleted from app build (a visible command) → still reports
    app:build --auth-alias, so genuine breaking changes are unaffected.

Checklist

  • I've considered possible cross-platform impacts (Mac, Linux, Windows)
  • I've considered possible documentation changes
  • I've considered analytics changes to measure impact
  • The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add — not user-facing, CI tooling only

`extractManifestSurface` treated every manifest command as public surface, so
renaming a flag on a `hidden` command failed the breaking change check even
though CONTRIBUTING.md scopes the stable command surface to what the CLI
actually exposes. Skip hidden commands when building the surface, which drops
them from the removed command, flag and env var scans alike.

Hidden-ness is read from each manifest independently, so a command that was
visible in the baseline and is hidden now still reports as removed: a PR can't
hide a command and strip its flags in one move without being flagged. An env
var shared with a visible command also stays tracked through that command.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Assisted-By: devx/a27b4557-3ac8-448a-8860-7a5ed6b20687
@nickwesselman
nickwesselman requested a review from a team as a code owner September 2, 2026 21:00
@github-actions github-actions Bot added the no-changelog This PR doesn't include a changeset entry. Is an internal only change not relevant to end users. label Sep 2, 2026
@amcaplan

amcaplan commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

I really appreciate the dedication to fixing broken windows in the experience of developing the CLI!

@nickwesselman

Copy link
Copy Markdown
Contributor Author

I'm going to abandon this as the check is non-blocking and there is some nuance. We might hide a command to deprecate it, in which case removing after would be the breaking change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-changelog This PR doesn't include a changeset entry. Is an internal only change not relevant to end users.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants