feat(lua): add lua-language-server type stubs for the yay global (#2884)

* feat(lua): add lua-language-server type stubs for the yay global Ship a meta/yay.meta.lua definition file that declares the `yay` global, all yay.opt fields, and every autocmd event payload so lua-language-server users get completion, hover docs, and typo detection without an "Undefined global `yay`" warning. - meta/yay.meta.lua: 232-line stub covering opt (45 fields), log, abort, create_autocmd with per-event overloads, and 14 payload classes for the 5 autocmd events (AURPreInstall, AURPostDownload, UpgradeSelect, PostInstall, SearchFilter). Return contracts for UpgradeSelect and SearchFilter are annotated. - doc/lua.md: add "Editor support" section with .luarc.json setup. - doc/init.lua: fix PostInstall example referencing pkg.installed, a field that does not exist on PostInstallPackage. - Makefile: install/uninstall meta/yay.meta.lua to $(PREFIX)/share/yay/meta/ so the documented /usr/share/yay/meta path exists on installed systems. Closes #2876 * doc(lua): fix api-since version to v13.0.1 * feat(lua): apply review feedback on type stubs Type opt fields as string unions with descriptions, rename to yay.d.lua per LuaLS docs, strip redundant comments from doc/init.lua, bump to v13.0.2. Tested everything again: go build, go test, lua-language-server, gendocs. * doc(lua): move "editor support", add hyperlinks added link to `init.lua` example in "location" paragraph having "editor support" paragraph at the very bottom of document didn't make any sense. user would want to have lsp editor support right after creating a file in config dir if ever. removed useless paragraph about `.luarc.json` location that already been explained aboved. added hyperlinks for luals extensions. couldn't find any special info for helix (unlike jetbrains), but it should be already covered by "other editors" --------- Co-authored-by: danielwerg <35052399+danielwerg@users.noreply.github.com>
2026-07-16 18:58:36 -04:00 · 2026-06-24 03:58:28 +05:30
parent 6e6d39d595
commit 80192ab1cb
4 changed files with 309 additions and 51 deletions
--- a/2
+++ b/2
@@ -95,6 +95,7 @@ install: build ${MOFILES}
 	install -Dm644 completions/bash $(DESTDIR)$(PREFIX)/share/bash-completion/completions/${PKGNAME}
 	install -Dm644 completions/zsh $(DESTDIR)$(PREFIX)/share/zsh/site-functions/_${PKGNAME}
 	install -Dm644 completions/fish $(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d/${PKGNAME}.fish
+	install -Dm644 meta/yay.d.lua $(DESTDIR)$(PREFIX)/share/${PKGNAME}/meta/yay.d.lua
 	for lang in ${LANGS}; do \
 		install -Dm644 ${LOCALEDIR}/$${lang}.mo $(DESTDIR)$(PREFIX)/share/locale/$$lang/LC_MESSAGES/${PKGNAME}.mo; \
 	done
@@ -106,6 +107,7 @@ uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/share/bash-completion/completions/${PKGNAME}
 	rm -f $(DESTDIR)$(PREFIX)/share/zsh/site-functions/_${PKGNAME}
 	rm -f $(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d/${PKGNAME}.fish
+	rm -f $(DESTDIR)$(PREFIX)/share/${PKGNAME}/meta/yay.d.lua
 	for lang in ${LANGS}; do \
 		rm -f $(DESTDIR)$(PREFIX)/share/locale/$$lang/LC_MESSAGES/${PKGNAME}.mo; \
 	done
--- a/doc/init.lua
+++ b/doc/init.lua
@@ -4,56 +4,53 @@
 -- or keep all of them and tune values. Command-line flags still override
 -- these values.

-- Strings
-yay.opt.aururl = "https://aur.archlinux.org" -- Base AUR URL.
-yay.opt.aurrpcurl = "" -- AUR RPC endpoint URL; empty uses default endpoint.
-yay.opt.build_dir = os.getenv("HOME") .. "/.cache/yay" -- Build/cache directory for AUR packages.
-yay.opt.editor = os.getenv("EDITOR") or os.getenv("VISUAL") or "vi" -- Editor command used for PKGBUILD edits; empty uses VISUAL/EDITOR.
-yay.opt.editor_flags = "" -- Extra flags passed to the editor command.
-yay.opt.makepkg_bin = "makepkg" -- makepkg executable (name in PATH or absolute path).
-yay.opt.makepkg_conf = "" -- makepkg.conf path; empty uses default makepkg config.
-yay.opt.pacman_bin = "pacman" -- pacman executable.
-yay.opt.pacman_conf = "/etc/pacman.conf" -- pacman.conf file path.
-yay.opt.redownload = "no" -- PKGBUILD download mode: "no" | "yes" | "all".
-yay.opt.git_bin = "git" -- git executable.
-yay.opt.gpg_bin = "gpg" -- gpg executable.
-yay.opt.gpg_flags = "" -- Extra flags passed to gpg.
-yay.opt.mflags = "" -- Extra flags passed to makepkg.
-yay.opt.sort_by = "" -- AUR search sort field: "votes" | "popularity" | "name" | "base" | "submitted" | "modified" | "".
-yay.opt.search_by = "name-desc" -- AUR search field: "name" | "name-desc" | "maintainer" | "submitter" | "depends" | "makedepends" | "optdepends" | "checkdepends" | "provides" | "conflicts" | "replaces" | "groups" | "keywords" | "comaintainers".
-yay.opt.git_flags = "" -- Extra flags passed to git.
-yay.opt.remove_make = "ask" -- Remove makedepends mode: "no" | "yes" | "ask" | "askyes".
-yay.opt.sudo_bin = "sudo" -- Privilege elevation command.
-yay.opt.sudo_flags = "" -- Extra flags passed to the sudo command.
-yay.opt.rebuild = "no" -- Build mode: "no" | "yes" | "tree" | "all".
-yay.opt.answer_clean = "" --  yay v13.0.1+ Pre-select clean menu answer: "" | "All" | "None" | "Installed" | "NotInstalled" (also accepts menu syntax: ranges, ^n, "abort").
-yay.opt.answer_diff = "" --  yay v13.0.1+ Pre-select diff menu answer: "" | "All" | "None" | "Installed" | "NotInstalled" (also accepts menu syntax: ranges, ^n, "abort").
-yay.opt.answer_edit = "" --  yay v13.0.1+ Pre-select edit menu answer: "" | "All" | "None" | "Installed" | "NotInstalled" (also accepts menu syntax: ranges, ^n, "abort").
+yay.opt.aururl = "https://aur.archlinux.org"
+yay.opt.aurrpcurl = ""
+yay.opt.build_dir = os.getenv("HOME") .. "/.cache/yay"
+yay.opt.editor = os.getenv("EDITOR") or os.getenv("VISUAL") or "vi"
+yay.opt.editor_flags = ""
+yay.opt.makepkg_bin = "makepkg"
+yay.opt.makepkg_conf = ""
+yay.opt.pacman_bin = "pacman"
+yay.opt.pacman_conf = "/etc/pacman.conf"
+yay.opt.redownload = "no"
+yay.opt.git_bin = "git"
+yay.opt.gpg_bin = "gpg"
+yay.opt.gpg_flags = ""
+yay.opt.mflags = ""
+yay.opt.sort_by = ""
+yay.opt.search_by = "name-desc"
+yay.opt.git_flags = ""
+yay.opt.remove_make = "ask"
+yay.opt.sudo_bin = "sudo"
+yay.opt.sudo_flags = ""
+yay.opt.rebuild = "no"
+yay.opt.answer_clean = ""
+yay.opt.answer_diff = ""
+yay.opt.answer_edit = ""

-- Integers
-yay.opt.request_split_n = 150 -- Max packages per AUR RPC request (use values > 0).
-yay.opt.completion_refresh_time = 7 -- Completion cache refresh days: -1 (never), 0 (always), >0 (every N days).
-yay.opt.max_concurrent_downloads = 1 -- Parallel PKGBUILD source downloads; 0 uses CPU count.
+yay.opt.request_split_n = 150
+yay.opt.completion_refresh_time = 7
+yay.opt.max_concurrent_downloads = 1

-- Booleans
-yay.opt.bottom_up = true -- Show AUR packages before repo packages in mixed results.
-yay.opt.sudo_loop = false -- Keep sudo session alive in the background during long builds.
-yay.opt.devel = false -- Check development/VCS packages on sysupgrade.
-yay.opt.clean_after = false -- Remove untracked files after install.
-yay.opt.keep_src = false -- Keep pkg/ and src/ after successful builds.
-yay.opt.provides = true -- Resolve matching providers when dependencies are ambiguous.
-yay.opt.pgp_fetch = true -- Prompt to import unknown PGP keys from validpgpkeys.
-yay.opt.clean_menu = true -- Show pre-build clean menu.
-yay.opt.diff_menu = true -- Show diff menu before building.
-yay.opt.edit_menu = false -- Show PKGBUILD edit menu before building.
-yay.opt.combined_upgrade = true -- Use combined repo+AUR upgrade flow on sysupgrade.
-yay.opt.use_ask = false -- Use pacman's --ask to auto-confirm known conflicts.
-yay.opt.batch_install = false -- Queue AUR package installs instead of installing each package immediately.
-yay.opt.single_line_results = false -- Use single-line search result format.
-yay.opt.separate_sources = true -- Separate query results by source (repo vs AUR).
-yay.opt.debug = false -- Enable debug logging and local init.lua lookup convenience.
-yay.opt.rpc = true -- Use AUR RPC for dependency/query operations.
-yay.opt.double_confirm = true -- Ask for confirmation before and after builds during upgrades.
+yay.opt.bottom_up = true
+yay.opt.sudo_loop = false
+yay.opt.devel = false
+yay.opt.clean_after = false
+yay.opt.keep_src = false
+yay.opt.provides = true
+yay.opt.pgp_fetch = true
+yay.opt.clean_menu = true
+yay.opt.diff_menu = true
+yay.opt.edit_menu = false
+yay.opt.combined_upgrade = true
+yay.opt.use_ask = false
+yay.opt.batch_install = false
+yay.opt.single_line_results = false
+yay.opt.separate_sources = true
+yay.opt.debug = false
+yay.opt.rpc = true
+yay.opt.double_confirm = true

 -- Hooks
 -- Run Lua before yay prints the upgrade exclusion menu. Return package names
@@ -114,9 +111,7 @@ yay.opt.double_confirm = true -- Ask for confirmation before and after builds du
 --   desc = "log every package yay installed",
 --   callback = function(event)
 --     for _, pkg in ipairs(event.data.packages) do
--       if pkg.installed then
--         yay.log.info(pkg.name .. " " .. pkg.version .. " installed (" .. pkg.source .. ")")
--       end
+--       yay.log.info(pkg.name .. " " .. pkg.version .. " (" .. pkg.source .. ")")
 --     end
 --   end,
 -- })
--- a/doc/lua.md
+++ b/doc/lua.md
@@ -11,6 +11,39 @@ yay uses the [Lua 5.1 interpreter](https://www.lua.org/manual/5.1/) to run `init
 1. `$XDG_CONFIG_HOME/yay/init.lua`
 2. `$HOME/.config/yay/init.lua`

+[Example init.lua](./init.lua)
+
+## Editor support
+
+<p class="api-since">Available from yay v13.0.2</p>
+
+yay ships a [lua-language-server](https://luals.github.io/) type definition file
+at [`meta/yay.d.lua`](../meta/yay.d.lua). It declares the `yay` global,
+every `yay.opt` field, and all autocmd event payloads so your editor can provide
+completion, hover documentation, and catch typos such as unknown option names or
+misspelled event fields.
+
+### Setup
+
+Point lua-language-server at the `meta/` directory via `workspace.library` in
+your [configuration file](https://luals.github.io/wiki/configuration/).
+With a `.luarc.json` in your project root, next to `init.lua`:
+
+```json
+{
+  "runtime": { "version": "Lua 5.1" },
+  "workspace": {
+    "library": ["/usr/share/yay/meta"]
+  }
+}
+```
+
+Replace `/usr/share/yay/meta` with the path to the `meta/` directory in your
+local yay checkout or installation. The runtime version should be `Lua 5.1`
+because yay runs `init.lua` through the [gopher-lua](https://github.com/yuin/gopher-lua) Lua 5.1 interpreter.
+
+lua-language-server is available for [VS Code](https://marketplace.visualstudio.com/items?itemName=sumneko.lua), [Neovim](https://luals.github.io/#neovim-install), [JetBrains](https://plugins.jetbrains.com/plugin/22315-sumnekolua), and [other editors](https://luals.github.io/#other-install) that support the Language Server Protocol.
+
 ## Setting options with `yay.opt`

 <p class="api-since">Available from yay v13.0.0</p>
--- a/meta/yay.d.lua
+++ b/meta/yay.d.lua
@@ -0,0 +1,228 @@
+-- yay Lua API type definitions for lua-language-server.
+--
+-- This is a meta file: lua-language-server loads it for type information only
+-- and never executes it. Add this directory to your `workspace.library` so the
+-- `yay` global, its options, and autocmd event payloads are recognised and
+-- type-checked in your init.lua. See doc/lua.md "Editor support" for setup.
+--
+-- API reference: https://github.com/Jguer/yay/blob/next/doc/lua.md
+
+---@meta
+
+-- Aliases
+
+---@alias yay.menuAnswer "" | "All" | "None" | "Installed" | "NotInstalled" | "abort"
+
+---@alias yay.Event "AURPreInstall" | "AURPostDownload" | "UpgradeSelect" | "PostInstall" | "SearchFilter"
+
+-- Options: yay.opt
+
+---@class yay.opt
+---@field aururl string Base AUR URL
+---@field aurrpcurl string AUR RPC endpoint URL; empty uses default endpoint.
+---@field build_dir string Build/cache directory for AUR packages.
+---@field editor string Editor command used for PKGBUILD edits; empty uses VISUAL/EDITOR.
+---@field editor_flags string Extra flags passed to the editor command.
+---@field makepkg_bin string makepkg executable (name in PATH or absolute path).
+---@field makepkg_conf string makepkg.conf path; empty uses default makepkg config.
+---@field pacman_bin string pacman executable.
+---@field pacman_conf string pacman.conf file path.
+---@field redownload "no" | "yes" | "all" PKGBUILD download mode.
+---@field git_bin string git executable.
+---@field gpg_bin string gpg executable.
+---@field gpg_flags string Extra flags passed to gpg.
+---@field mflags string Extra flags passed to makepkg.
+---@field sort_by "votes" | "popularity" | "name" | "base" | "submitted" | "modified" | "" AUR search sort field.
+---@field search_by "name" | "name-desc" | "maintainer" | "submitter" | "depends" | "makedepends" | "optdepends" | "checkdepends" | "provides" | "conflicts" | "replaces" | "groups" | "keywords" | "comaintainers" AUR search field.
+---@field git_flags string Extra flags passed to git.
+---@field remove_make "no" | "yes" | "ask" | "askyes" Remove makedepends mode.
+---@field sudo_bin string Privilege elevation command.
+---@field sudo_flags string Extra flags passed to the sudo command.
+---@field rebuild "no" | "yes" | "tree" | "all" Build mode.
+---@field answer_clean yay.menuAnswer yay v13.0.1+ Pre-select clean menu answer (also accepts menu syntax: ranges, ^n).
+---@field answer_diff yay.menuAnswer yay v13.0.1+ Pre-select diff menu answer (also accepts menu syntax: ranges, ^n).
+---@field answer_edit yay.menuAnswer yay v13.0.1+ Pre-select edit menu answer (also accepts menu syntax: ranges, ^n).
+---@field request_split_n integer Max packages per AUR RPC request (use values > 0).
+---@field completion_refresh_time integer Completion cache refresh days: -1 (never), 0 (always), >0 (every N days).
+---@field max_concurrent_downloads integer Parallel PKGBUILD source downloads; 0 uses CPU count.
+---@field bottom_up boolean Show AUR packages before repo packages in mixed results.
+---@field sudo_loop boolean Keep sudo session alive in the background during long builds.
+---@field devel boolean Check development/VCS packages on sysupgrade.
+---@field clean_after boolean Remove untracked files after install.
+---@field keep_src boolean Keep pkg/ and src/ after successful builds.
+---@field provides boolean Resolve matching providers when dependencies are ambiguous.
+---@field pgp_fetch boolean Prompt to import unknown PGP keys from validpgpkeys.
+---@field clean_menu boolean Show pre-build clean menu.
+---@field diff_menu boolean Show diff menu before building.
+---@field edit_menu boolean Show PKGBUILD edit menu before building.
+---@field combined_upgrade boolean Use combined repo+AUR upgrade flow on sysupgrade.
+---@field use_ask boolean Use pacman's --ask to auto-confirm known conflicts.
+---@field batch_install boolean Queue AUR package installs instead of installing each package immediately.
+---@field single_line_results boolean Use single-line search result format.
+---@field separate_sources boolean Separate query results by source (repo vs AUR).
+---@field debug boolean Enable debug logging and local init.lua lookup convenience.
+---@field rpc boolean Use AUR RPC for dependency/query operations.
+---@field double_confirm boolean Ask for confirmation before and after builds during upgrades.
+
+-- Logging: yay.log
+
+---@class yay.log
+---@field debug fun(...: any)
+---@field info fun(...: any)
+---@field warn fun(...: any)
+---@field error fun(...: any)
+
+-- Event payloads: AURPreInstall / AURPostDownload
+-- Both events share the same data shape; only the `event` string differs.
+
+---@class yay.AURPreInstallPackage
+---@field name string
+---@field version string
+---@field local_version string
+---@field reason string
+---@field upgrade boolean
+---@field devel boolean
+
+---@class yay.AURPreInstallSRCINFO
+---@field pkgbase string
+---@field pkgver string
+---@field pkgrel string
+---@field epoch string
+---@field version string
+---@field pkgdesc string
+---@field url string
+---@field arch string[]
+---@field license string[]
+---@field depends string[]
+---@field makedepends string[]
+---@field checkdepends string[]
+---@field optdepends string[]
+---@field provides string[]
+---@field conflicts string[]
+---@field replaces string[]
+
+---@class yay.AURInstallData
+---@field base string
+---@field dir string
+---@field pkgbuild_path string
+---@field srcinfo_path string
+---@field pkgbuild string
+---@field version string
+---@field last_modified integer
+---@field installed boolean
+---@field packages yay.AURPreInstallPackage[]
+---@field srcinfo yay.AURPreInstallSRCINFO
+
+---@class yay.AURPreInstallEvent
+---@field event "AURPreInstall"
+---@field match string
+---@field data yay.AURInstallData
+
+---@class yay.AURPostDownloadEvent
+---@field event "AURPostDownload"
+---@field match string
+---@field data yay.AURInstallData
+
+-- Event payloads: UpgradeSelect
+
+---@class yay.UpgradeSelectPackage
+---@field id integer
+---@field name string
+---@field base string
+---@field repository string
+---@field local_version string
+---@field remote_version string
+---@field reason string
+---@field last_modified integer
+---@field maintainer string
+
+---@class yay.UpgradeSelectData
+---@field upgrades yay.UpgradeSelectPackage[]
+---@field pulled_dependencies yay.UpgradeSelectPackage[]
+
+---@class yay.UpgradeSelectEvent
+---@field event "UpgradeSelect"
+---@field data yay.UpgradeSelectData
+
+---@class yay.UpgradeSelectResult
+---@field exclude string[]
+---@field skip_menu boolean
+
+-- Event payloads: PostInstall
+
+---@class yay.PostInstallPackage
+---@field name string
+---@field version string
+---@field local_version string
+---@field source string
+---@field reason string
+
+---@class yay.PostInstallData
+---@field packages yay.PostInstallPackage[]
+
+---@class yay.PostInstallEvent
+---@field event "PostInstall"
+---@field data yay.PostInstallData
+
+-- Event payloads: SearchFilter
+
+---@class yay.SearchResultPackage
+---@field source string
+---@field name string
+---@field description string
+---@field base string
+---@field votes integer
+---@field popularity number
+---@field first_submitted integer
+---@field last_modified integer
+
+---@class yay.SearchFilterData
+---@field results yay.SearchResultPackage[]
+
+---@class yay.SearchFilterEvent
+---@field event "SearchFilter"
+---@field data yay.SearchFilterData
+
+---@class yay.SearchResultRef
+---@field source string
+---@field name string
+
+-- create_autocmd opts: one per event so the callback payload is typed.
+
+---@class yay.AURPreInstallOpts
+---@field desc? string
+---@field callback fun(event: yay.AURPreInstallEvent)
+
+---@class yay.AURPostDownloadOpts
+---@field desc? string
+---@field callback fun(event: yay.AURPostDownloadEvent)
+
+---@class yay.UpgradeSelectOpts
+---@field desc? string
+---@field callback fun(event: yay.UpgradeSelectEvent): yay.UpgradeSelectResult?
+
+---@class yay.PostInstallOpts
+---@field desc? string
+---@field callback fun(event: yay.PostInstallEvent)
+
+---@class yay.SearchFilterOpts
+---@field desc? string
+---@field callback fun(event: yay.SearchFilterEvent): yay.SearchResultRef[]?
+
+---@overload fun(event: "AURPreInstall", opts: yay.AURPreInstallOpts)
+---@overload fun(event: "AURPostDownload", opts: yay.AURPostDownloadOpts)
+---@overload fun(event: "UpgradeSelect", opts: yay.UpgradeSelectOpts)
+---@overload fun(event: "PostInstall", opts: yay.PostInstallOpts)
+---@overload fun(event: "SearchFilter", opts: yay.SearchFilterOpts)
+---@class yay.create_autocmd
+
+-- The yay global
+
+---@class yay
+---@field opt? yay.opt
+---@field log? yay.log
+---@field abort? fun(reason: string)
+---@field create_autocmd? yay.create_autocmd
+
+---@type yay
+yay = {}