casey / casey/just

Improve dynamic completions

Open
#2,406 2 comments 7 reactions 0 assignees View on GitHub
completions
Dominant language
Rust
Stars
35.8k
Forks
846
Avg merge
27m
Merged PRs (30d)
3

Description

Just previously used clap's statically generated completion scripts. These scripts would complete flags and options, but wouldn't complete recipes, since that requires invoking just itself to find and parse the justfile. To remedy this, we started patching the generated completion scripts.

This slowly turned into a maintainance nightmare, as the patches grew in number and complexity, and had to be manually adapted every time the base completion scripts changed.

Clap has a new dynamic completion engine, tracked in https://github.com/clap-rs/clap/issues/3166.

In #3167 I switched to the new completion engine. Strictly speaking, this was a regression, since we lost the ability to complete recipes, but I didn't want to try to do everything in one PR, so I thought it was better to merge it and add back the missing functionally in follow-up PRs.

To do:
- [ ] Bash splits completion arguments on `:`, which breaks completion of `::`-separate recipe paths. We should upstream a fix to `clap_complete`, since it's basically never correct to split on `:`. I have a draft PR open for this: https://github.com/clap-rs/clap/pull/6311
- [x] Complete arguments with variable names (suffixed with `=`, recipes, and file paths (since they could be recipe arguments)
- [ ] Complete arguments more intelligently. I'm not sure how much we can do here, but it would be ideal to only complete overrides if we haven't gotten a recipe name or an argument, and to only complete recipes when we're in a position where we're expecting a recipe (i.e., we're not in position where we're completing a recipe argument). This may be tough. We don't know where exactly in the positional arguments we're completing, so we don't necessarily know what we're completing. However, this enables a bunch of stuff, like showing the parameter name when completing a recipe parameter, or completing flags and options.
- [x] Complete variable names for `--set`
- [ ] Support proper completions for nushell
- [ ] Don't complete variable names in value position for `--set`, i.e., `--set foo `
- [x] Complete recipes for `--show`
- [ ] Look through all arguments for opportunities to improve completions (e.g., only complete files or directories, or add a new custom completer)
- [x] Add instructions for each supported shell for how to load shell completion scripts, including how to lazy load them
- [x] Close all PRs and issues related to the old completion scripts
- [ ] The patched zsh completion script had a nice feature where if pressed tab after completing a recipe, it would show you the recipe as a hint message. This was nice, we should try to replicate it.
- [ ] When completing recipes, should we show the docs, the parameters, or both?
- [ ] When completing a variable for an override, we should complete `VAR=` and leave the cursor after the `=` (`-qS =` in zsh) so the user doesn't have to backspace.
- [ ] Complete paths with `~`, `~USER`, `$VARIABLE` (maybe not wise, since variable references are different across shells), and anything else? (I think this is only broken in zsh)
- [x] Complete group names for `--group`
- [ ] Complete modules for `--list` (seems to be a bug in clap)
- [x] Complete recipe path for `--usage`
- [ ] `--chooser`, `--cygpath`, `--shell`, `--command` (first only) complete files and binary names in PATH. (this is maybe crazy, since there might be many binaries on PATH)
- [ ] `--dotenv-filename` Maybe we should complete files? It's not technically correct, since they should be filenames only, but it's probably better than not completing files.
- [ ] Report back to clap with any feedback on integration (felt so good to nuke the old scripts, huge improvement in functionality and consistency, I think maybe I would make it more clear in documentation that the feature is unstable but very usable since I probably waited too long to try it, we are parsing args, and we rely on being able to remove the arg prefix, and any kind of testing relies on setting the argument correctly to call the binary, bash alias completion depends on knowing the name of the completion function)
- [ ] Figure out a way to print errors in completion engine
- [ ] Handle space-separated paths in arguments and `--show`
- [ ] Reconsider including recipe doc comments in completions, it makes them take up much more space
- [ ] Autocomplete fallback recipes (filter recipes can cannot be executed via fallback)
- [ ] Don't complete options after positional arguments (this is a clap bug)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.