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>

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,
 -- })