Loading out-of-repo autocompletion specs

pzmarzly commented 9 months ago

Sanity checks

[X] I have searched github.com/withfig/fig/issues and there are no duplicates of my feature

Feature Details

Currently Fig and Inshellisense both use withfig/autocomplete for completion specs. These are just TS files that compile to JS (and from what I see, could be compiled to JSON as well with no loss in functionality).

This "big repo" approach worked great for increasing adoption of TS types, in form of DefinitelyTyped repo. But at some point, it became more beneficial to let maintainers of various packages to ship their own type definitions together with their packages. So now many maintainers of JS packages ship type definitions as part of their JS package.

I'd like to see the same thing happen here. Many popular .deb / .rpm files that care a lot about UX already have structure like:

/usr/bin/mycli - actual binary
/usr/share/doc/mycli - GNU docs
/usr/share/locale/../LC_MESSAGES/mycli.mo
/usr/share/man/man1/mycli.1.gz - man docs
/usr/share/bash-completion/completions/mycli
/usr/share/zsh/site-functions/_mycli

I suspect some will want to also ship their own autocomplete specs. I would imagine this could be something like /usr/share/fig-autocomplete/mycli.json. Then Fig could scan this directory at startup and load the definitions. If some spec was present both in /usr/share/fig-autocomplete and in withfig/autocomplete repo, Fig should choose /usr/share/fig-autocomplete.

What benefits would that have?

Let teams ship internal CLIs with Fig definitions (the teams don't want to show UIs of their companies' internal CLIs to the world, maintainers of withfig/autocomplete probably don't want to accept these)
The autocomplete specs will be meant for the version of the CLI that's installed on the machine - so Fig will not suggest a flag that was only introduced in newer version of that CLI
Less burden for withfig/autocomplete's maintainers as Fig and Inshellisense adoption grows
Possibility of convincing some non-GitHub projects to maintain their Fig specs (e.g. GNU, GNOME and KDE all have their own code hosting, so I expect maintainers may not like to have to use GitHub to update the specs)
Linux distributions could document their custom flags and patches

pzmarzly commented 9 months ago

I have missed the docs part that says about ~/.fig/autocomplete/build directory. So ignore most of my post. Still, could we have a machine-wide /usr/share/fig/autocomplete/build?

mschrage commented 8 months ago

I like this idea. Shouldn't be too difficult to add a machine-wide completion spec directory, in addition to ~/.fig/autocomplete/build

grant0417 commented 8 months ago

I like the idea of a "fig path" like FPATH in zsh, we could load completions from these locations in order:

~/.fig-autocomplete
$XDG_DATA_HOME/fig-autocomplete or ~/.local/share/fig-autocomplete
/usr/share/fig-autocomplete
public repo data

withfig / fig