Report likely typos in parameters of catch-all commands - #6392

No actionable comments were generated in the recent review. 🎉

sequenceDiagram
  participant User
  participant Subcommand
  participant SynopsisValidator
  participant get_suggestion
  User->>Subcommand: provide associative arguments
  Subcommand->>SynopsisValidator: validate unknown arguments
  Subcommand->>get_suggestion: request filtered suggestion
  get_suggestion-->>Subcommand: return alias or distance-based suggestion
  Subcommand-->>User: accept arguments or report validation error

Merge Risk: ⚪ Minimal · up to a12cf

Catch-all parameters retain pass-through behavior while close documented-option matches warn without changing command exit status.

• 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.

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

Codecov Report

❌ Patch coverage is 93.61702% with 3 lines in your changes missing coverage. Please review.

📢 Thoughts on this report? Let us know!

I pulled this branch and tested it against the current entity-command main. Sharing one thing I noticed, since some entity-command docs have changed after this PR was opened.

entity-command#643 merged today and documents --year, --monthnum and --day on wp post list. With those in the candidate set, a few common WP_Query arguments now become close matches:

wp post list --cat=5
Error: unknown --cat parameter. Did you mean '--day'?

wp post list --tag=x
Error: unknown --tag parameter. Did you mean '--day'?

wp post list --feed=x
Error: unknown --feed parameter. Did you mean '--field'?

--cat is especially interesting because it is also used as a passing example in the PR description. Removing global parameters fixed the earlier --path collision, but documenting more read-command parameters can introduce new collision targets from the command's own documented args.

I had built a similar local check earlier, and it had two extra conservative guards: skip comparisons where the shorter name is under 5 characters, and pass when one name is a prefix of the other. That avoids the --cat, --tag and --feed cases, but it still does not solve the broader site_id class of false positive.

So this seems less like a matcher tuning issue and more like a scope issue. Read commands have open-ended query args, and every newly documented parameter can become another collision target. Write commands are different: the accepted field set is much more enumerable, and the damage from a silent typo is higher.

This seems to support restricting the near-match check to write commands, unless there is another way you are thinking about containing read-command false positives.

Happy to share the small sweep script if useful.

Thanks for testing 👍

For these 3 particular arguments it's a matter of actually documenting them. Except --feed, which is a query var for things like RSS feeds, but not something you'd explicitly pass to WP_Query.

Reproduced all three, and documenting them is now wp-cli/entity-command#645 — --cat, --tag and --category_name, documentation only, since they already work.

--feed stays undocumented, as @swissspidy says: it is a query var WordPress fills in when routing a request. Worth adding that it is not merely uninteresting — passing it to WP_Query filters nothing at all, so documenting it would advertise a no-op, which is the thing entity-command#643 set out to remove.

Your "new collision target" point, measured

I swept the whole WP_Query query-var list against the documented parameters at this PR's threshold:

That third row is your point exactly. tag_id is a real filter and documenting it looks obviously right, but it sits within two edits of both page_id and tag__in, so it hands back precisely as many false positives as documenting cat and tag removes. I left it out of #645 for that reason — which means "should this be documented?" now partly depends on what else is documented, an awkward coupling worth naming.

The two that survive are both the same kind of thing: feed and tb are query vars WordPress sets when routing a request, not arguments anyone passes to WP_Query. Neither is worth documenting just to silence a suggestion.

On your conservative guards

The < 5 characters guard would also suppress --cta→--cat, --tsg→--tag, --dey→--day — real typos of exactly the short parameters this PR documents. Given documenting cat and tag fixes those two cases outright, the guard would cost more than it buys.

The prefix guard is different and cheaper: tag__in/tag_id and page_id/p are prefix relationships, and no plausible typo is a strict prefix of the thing it was meant to be. That one would survive the tag_id case without suppressing genuine typos.

One caveat on my numbers

They come from Utils\get_suggestion() against the parsed parameter list, not from end-to-end runs. I could not get the error to reproduce end-to-end for wp post list in my environment — wp cli info --fomat=json and wp post meta list 1 --fomat=csv both error correctly, but wp post list --fomat=csv is accepted silently, with WP_CLI_ROOT pointing at this branch in all three. Since you did see it fire, I assume something environmental on my side rather than a defect, but it may be worth a second look that the catch-all path fires for wp post list specifically — that is the command this whole discussion is about.

Generated by Claude Code

One more small matcher detail I noticed while checking this branch.

The current path seems to run get_suggestion() on the raw argument names. That catches a pure dash/underscore typo like --user-pass → --user_pass, but it can miss a dash-form typo that also has one normal typo:

post-titel   vs post_title    raw distance 3, normalized distance 2
post-stauts  vs post_status   raw distance 3, normalized distance 2
user-emial   vs user_email    raw distance 3, normalized distance 2
frist-name   vs first_name    raw distance 3, normalized distance 2

So examples like wp user update 1 --user-emial=x@y.co can still pass silently even though they are very close to a documented write-field name.

Normalizing - to _ before measuring the distance seems to catch this class without changing the threshold.

Hmm interesting example. Not sure I'd apply such normalization though, it's basically the same as increasing the threshold.

Considering AI agents as consumers, user-pass vs user_pass is more likely, so I'd rather focus on that, which the current implementation covers.

Follow-up on my own comment above, since entity-command#645 moved past what I described there.

I'd written that tag_id was left out of #645 because documenting it alone added two false positives (--page_id→--tag_id, --tag__in→--tag_id). That's no longer the state of the PR — it grew to cover the complete WP_Query::parse_query() argument list (63 options, all from that docblock), which includes the rest of the tag__* family, page_id, paged, and so on. With the whole set documented, both tag_id and page_id are in and cost nothing:

So the actual finding is the opposite of what I said in the moment: partial documentation of a family creates false positives by stranding whichever neighbor isn't yet documented, and documenting all of it converges back to the floor of 2 — the two query vars (feed, tb) that aren't filters at all. Worth having on record here since it's a general shape, not specific to wp post list: if this check ever gets applied to another catch-all command, documenting a family incrementally is the wrong order to do it in.

Generated by Claude Code