docs(events): Lua types for autocmd event-data #38518

Problem:
  No LuaLS types for event-data fields (ev.data). Types are only
  documented ad hoc in scattered locations.

Solution:
  Add runtime/lua/vim/_meta/events.lua defining vim.event.<name>.data
  classes for events that provide ev.data. Reference the types from
  each event's help in autocmd.txt, lsp.txt, and pack.txt.
(cherry picked from commit 2cb240319b)

runtime/doc/autocmd.txt

@@ -226,6 +226,17 @@ autocommands, this doesn't happen.
 You can use the 'eventignore' option to ignore a number of events or all
 events.
 
+Events that provide |event-data| have a matching `vim.event.<name>.data` type
+defined in `runtime/lua/vim/_meta/events.lua`. You can use @cast to narrow
+`ev.data` for type-checking and completion: >lua
+
+	vim.api.nvim_create_autocmd('LspAttach', {
+	  callback = function(ev)
+	    ---@cast ev {data: vim.event.lspattach.data}
+	    local client = vim.lsp.get_client_by_id(ev.data.client_id)
+	  end,
+	})
+<
 							*events* *{event}*
 Nvim recognizes the following events.  Names are case-insensitive.
 
@@ -780,10 +791,11 @@ MarkSet				After a |mark| is set by |m|, |:mark|, and
 				mark name (e.g. `[ab]` matches `a` or `b`, `*`
 				matches all).
 
-				The |event-data| has these keys:
+				The |event-data| has these keys (type: `vim.event.markset.data`):
 				- name: Mark name (e.g. "a")
 				- line: Mark line.
 				- col: Mark column.
+				See `vim.event.markset.data`.
 
 							*MenuPopup*
 MenuPopup			Just before showing the popup menu (under the
@@ -831,6 +843,7 @@ Progress						*Progress*
 						 made for this progress item
 					data: arbitaray data sent with
 					progress message
+				See `vim.event.progress.data`.
 				Usage example:
 >lua
 		vim.api.nvim_create_autocmd('Progress', {
@@ -1107,6 +1120,7 @@ TermRequest			When a |:terminal| child process emits an OSC,
 				  position of the cursor when the sequence was
 				  received (line number may be <= 0 if the
 				  position is no longer in the buffer)
+				See `vim.event.termrequest.data`.
 
 				This is triggered even when inside an
 				autocommand defined without |autocmd-nested|.
@@ -1117,6 +1131,7 @@ TermResponse			When Nvim receives a DA1, OSC, DCS, or APC response from
 				|event-data| is a table with the following fields:
 
 				- sequence: the received sequence
+				See `vim.event.termresponse.data`.
 
 				This is triggered even when inside an
 				autocommand defined without |autocmd-nested|.

runtime/doc/lsp.txt

@@ -689,7 +689,7 @@ EVENTS                                                            *lsp-events*
 LspAttach                                                          *LspAttach*
     After an LSP client performs "initialize" and attaches to a buffer. The
     |autocmd-pattern| is the buffer name. The client ID is passed in the
-    Lua handler |event-data| argument.
+    Lua handler |event-data| argument. See `vim.event.lspattach.data`.
 
     Example: >lua
     vim.api.nvim_create_autocmd('LspAttach', {
@@ -722,7 +722,7 @@ LspAttach                                                          *LspAttach*
 LspDetach                                                          *LspDetach*
     Just before an LSP client detaches from a buffer. The |autocmd-pattern| is
     the buffer name. The client ID is passed in the Lua handler |event-data|
-    argument.
+    argument. See `vim.event.lspdetach.data`.
 
     Example: >lua
     vim.api.nvim_create_autocmd('LspDetach', {
@@ -746,7 +746,7 @@ LspNotify                                                          *LspNotify*
     LSP server.
 
     The client_id, LSP method, and parameters are sent in the Lua handler
-    |event-data| table argument.
+    |event-data| table argument. See `vim.event.lspnotify.data`.
 
     Example: >lua
     vim.api.nvim_create_autocmd('LspNotify', {
@@ -774,7 +774,7 @@ LspProgress                                                       *LspProgress*
 
     The Lua handler |event-data| argument has `client_id` and `params`
     properties, where `params` is the request params sent by the server (see
-    `lsp.ProgressParams`).
+    `lsp.ProgressParams`). See `vim.event.lspprogress.data`.
 
     Examples:
 
@@ -813,6 +813,7 @@ LspRequest                                                        *LspRequest*
     request (described at |vim.lsp.Client|, {requests} field). If the request
     type is `complete`, the request will be deleted from the client's pending
     requests table after processing the event handlers.
+    See `vim.event.lsprequest.data`.
 
     Example: >lua
     vim.api.nvim_create_autocmd('LspRequest', {
@@ -841,7 +842,7 @@ LspTokenUpdate                                                *LspTokenUpdate*
     when an existing token becomes visible for the first time. The
     |autocmd-pattern| is the buffer name. The Lua handler |event-data|
     argument has the client ID and token (see
-    |vim.lsp.semantic_tokens.get_at_pos()|).
+    |vim.lsp.semantic_tokens.get_at_pos()|). See `vim.event.lsptokenupdate.data`.
 
     Example: >lua
     vim.api.nvim_create_autocmd('LspTokenUpdate', {

runtime/doc/pack.txt

@@ -369,6 +369,8 @@ Each event populates the following |event-data| fields:
 • `spec` - plugin's specification with defaults made explicit.
 • `path` - full path to plugin's directory.
 
+See `vim.event.packchanged.data` and `vim.event.packchangedpre.data`.
+
 These events can be used to execute plugin hooks. For example: >lua
     local hooks = function(ev)
       -- Use available |event-data|

runtime/lua/vim/_meta/events.lua

@@ -0,0 +1,56 @@
+--- @meta
+error('Cannot require a meta file')
+
+--- @class vim.event.lspattach.data
+--- @field client_id integer
+
+--- @class vim.event.lspdetach.data
+--- @field client_id integer
+
+--- @class vim.event.lspnotify.data
+--- @field client_id integer
+--- @field method string
+--- @field params table
+
+--- @class vim.event.lspprogress.data
+--- @field client_id integer
+--- @field params lsp.ProgressParams
+
+--- @class vim.event.lsprequest.data
+--- @field client_id integer
+--- @field request_id integer
+--- @field request table
+
+--- @class vim.event.lsptokenupdate.data
+--- @field client_id integer
+--- @field token table
+
+--- @class vim.event.markset.data
+--- @field name string
+--- @field line integer
+--- @field col integer
+
+--- @class vim.event.packchanged.data
+--- @field active boolean
+--- @field kind string
+--- @field spec vim.pack.Spec
+--- @field path string
+
+--- @class vim.event.packchangedpre.data : vim.event.packchanged.data
+
+--- @class vim.event.progress.data
+--- @field id any
+--- @field text string[]
+--- @field data? table
+--- @field percent? integer
+--- @field source? string
+--- @field status? string
+--- @field title? string
+
+--- @class vim.event.termrequest.data
+--- @field sequence string
+--- @field terminator string
+--- @field cursor integer[]
+
+--- @class vim.event.termresponse.data
+--- @field sequence string

runtime/lua/vim/pack.lua

@@ -175,6 +175,8 @@
 ---- `spec` - plugin's specification with defaults made explicit.
 ---- `path` - full path to plugin's directory.
 ---
+---See `vim.event.packchanged.data` and `vim.event.packchangedpre.data`.
+---
 --- These events can be used to execute plugin hooks. For example:
 ---```lua
 ---local hooks = function(ev)