Added a script to generate autocomplete files using EmmyLua annotations

[folke]

I've created a python script that uses build/docs.json to generate Hammerspoon API stubs using EmmyLua annotations

These kinds of annotations are supported by the following lsp servers:

• lua-language-server (most complete)
• EmmyLua-LanguageServer

Plugins exist for VScode, IntelliJ, vim, Emacs, ... to work with those lsp servers

Let me know your thoughts!

✅ TODO

• cleaner parsing of function parameter signatures
• better parsing of function return types
• more type annotations for variables and constants
• generate stubs for spoons
• create a wiki page on how to use this. Either by copying the types directory or including it as a library

📦 Building and using the Hammerspoon stubs

Checkout this branch and run the following:

$ make build/stubs

You now have two options to start using the stubs:

1. copy the generated directory to your .hammerspoon directory (or any other project where you need hs complation to work)
2. add the build/stubs folder as an external library. For lua-language-server, add the folllowing to your workspace settings in vscode:

{
  "Lua.workspace.library": {
    "/Users/folke/projects/hammerspoon/build/stubs": true
  }
}

❗ Don't just symlink the stubs in your project directory! In at least lua-language-server, there's an issue with symlinked source roots and autocompletion won't work.

❓ FAQ

Why not just add /Applications/Hammerspoon.app/Contents/Resources/extensions/ as an external library to the lsp config?

Simply adding the hammerspoon extensions directory as an external library doesn't work for a couple of reasons:

• class instances, constructors and function return would not get proper autocompletion
• _coresetup populates the hs[string] table with all modules. LSP servers have a hard time dealing with this and think all functions/methods/variables anywhere are valid auto completions for every module. With the generated stubs, auto completion works for all HS functionality.

How could this be distributed?

• possibly as an additional zip file as part of the Github release
• as a directory in the Hammerspoon.app. For example /Applications/Hammerspoon.app/Contents/Resources/stubs

🎨 Screenshots

Completion for Spoons

[codecov]

Codecov Report

Merging #2530 (ffb9606) into master (3713f70) will decrease coverage by 1.48%.
The diff coverage is n/a.

❗ Current head ffb9606 differs from pull request most recent head cd0f6b5. Consider uploading reports for the commit cd0f6b5 to get more accurate results

@@            Coverage Diff             @@
##           master    #2530      +/-   ##
==========================================
- Coverage   27.22%   25.73%   -1.49%     
==========================================
  Files         180      177       -3     
  Lines       36148    35239     -909     
==========================================
- Hits         9841     9069     -772     
+ Misses      26307    26170     -137     

[asmagill]

Interesting. I probably won't be able to test this for a few days (my current go to editor, BBEdit, doesn't support lsp servers, so I'm going to have to take a look at Nova or VSCode).

Just to make sure I understand, I only need to run the python script once to build the stubs each time the supplied docs.json file is changed, correct?

[folke]

That is correct!

Ive also added an entry for it to the Makefile.

$ make build/stubs

[folke]

With the new improvements, auto completion works pretty much everywhere. For more info, see the updated description 🔝

[folke]

Just added stub generating for spoons as well

[asmagill]

Does the python script require any special packages to be installed or will it run with the stock macOS installation of python?

[folke]

Standard python /usr/bin/python should work. There's no external dependencies on other packages either.

[asmagill]

I will try and review this week (got sidetracked multiple times since I last posted here), but I am wondering if this might be better as a Spoon?

Since it can be built by anyone with the stock macOS python and the json file... I don't think there is anything that requires it to be part of a release build, but correct me if I'm wrong... a little file date checking and it a spoon could trigger a rebuild for you when Hammerspoon is updated.

At any rate, I'll give this a closer look soon.

[folke]

That's actually a great idea. Since the Spoons directory is a subdirectory of the user's .hammerspoon directory, the stubs inside for example AutoComplete.spoon would work as is, without needing to define the library in the LSP config.

Another benefit is that auto completion would also work for non-official spoons, since we can generate the stubs on the fly when needed.

Is this something you would be interested to have as part of the official spoons?

If so, what name would you suggest? AutoComplete.spoon?

[cmsj]

@folke apologies for not being involved in this PR so far. I think having it as a Spoon is a great idea, and I would definitely accept it into the official repo.

Regarding the name - I wonder if we could come up with something a little more specific than AutoComplete, although I don't have any brilliant suggestions.

[folke]

@cmsj ok, great. Will create a Spoon once I have some time. Thanks!

[stickler-ci]

W504 line break after binary operator

[github-actions]

This pull request does not contain a valid label. Please add one of the following labels: pr-fix, pr-change, pr-feature, pr-maintenance

[folke]

@cmsj I created a Spoon as discussed.

The implementation is now also fully in Lua, so Python is no longer needed.

[taybart]

Any word on this PR?