Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rfc for improving command suggestions #339

Merged
merged 3 commits into from
Apr 19, 2021

Conversation

nlf
Copy link
Contributor

@nlf nlf commented Mar 10, 2021

this is intended to improve discoverability of a working command when a user runs something that does not work, notably this is an approach to addressing the needs of users who expect npm foo to work. instead of making an assumption that they want a script or binary, we will suggest that they try an explicit command that does one of those actions.

References

Related to #336
Related to #332
Related to #279

Co-authored-by: Jordan Harband <ljharb@gmail.com>

I would suggest that we add a blessed property to errors thrown by commands `suggestions`. In the CLI framework, if a command rejects with an error that has this property, we display the suggestions.

As for discovering the suggestions, we already have logic to find similarly named scripts based on levenshtein distance. This would need to be abstracted to a utility that can be consumed in `run-script` as well as `exec` and `help-search`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if we do this, we could have the commands do something like throw Object.assign(new Error('unknown command'), { suggestions: listOfEveryAvailableCommand }) and let the Levenshtein distance pick the best ones to prompt?

@isaacs
Copy link
Contributor

isaacs commented Mar 11, 2021

I think (ironically) this RFC is blending together a few things into one, and in the spirit of this RFC, it should be made explicit. They are:

  1. Unknown top level commands suggesting run/exec
  2. Misspelling affordances (like npm isntall)
  3. Unambiguous partial abbrev spellings for known things (like npm ins for npm install)
  4. "Blessed" affordances/shorthands like the npm i alias for npm install

For (1), I think that this is exactly the right approach, and seems to be where we keep landing every time we discuss the tradeoffs involved in making npm tsc work like yarn.

For (2), this seems reasonable enough, though it is a breaking change, and definitely not uncontroversial. We could do a lot worse than copying git, and we have enough commands that some of the affordances have started to get a bit cluttered.

For (3), it's worth noting that git recently added support for abbreviations on command-line switches, but not on top level commands. If a command is an unambiguous abbreviation for a known top-level command, it seems like we have enough to know what the user intended.

For (4), I think the list could be examined and we could make some changes, but I am going to die on the hill of npm i and npm t continuing to work as they currently do. Making the user type out the full word for those common commands just seems rude.

Ideas for a follow-up RFC:

  • Config option to tell npm to just take the first suggestion.
  • Config options to define shorthands and aliases.
  • Choice in the prompt to save the suggestion as an alias when we do have an interactive mode, so users who truly cannot stop typing hlep can opt into the affordance.
  • Similar rejection/suggestion for CLI configs, in some future time when we can drop support for parsing unknown config options.

@darcyclarke darcyclarke merged commit 830d8db into latest Apr 19, 2021
@darcyclarke darcyclarke removed the Agenda will be discussed at the Open RFC call label Apr 19, 2021
@isaacs isaacs mentioned this pull request Apr 20, 2021
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.

4 participants