fix(lua): not obvious which _meta/ files are generated #39035

Problem:
- Not obvious which _meta/ are generated and which should be edited
  manually.
- The require guard (`error('Cannot require a meta file')`) is not
  consistently present in all meta files.

Solution:
- Update headers.
- Add require() guard to all meta files.
- Rename generated meta files with `.gen.lua`.

.gitattributes

@@ -5,11 +5,8 @@
 runtime/doc/*   linguist-documentation
 runtime/doc/builtin.txt linguist-generated
 
-runtime/lua/vim/_meta/vimfn.lua linguist-generated
-runtime/lua/vim/_meta/vvars.lua linguist-generated
-runtime/lua/vim/_meta/api.lua linguist-generated
-runtime/lua/vim/_meta/api_keysets.lua linguist-generated
-runtime/lua/vim/_meta/options.lua linguist-generated
+# api.gen.lua, vimfn.gen.lua, etc.
+runtime/lua/vim/_meta/*.gen.lua linguist-generated
 
 src/xdiff/**    linguist-vendored
 src/cjson/**    linguist-vendored

.luacheckrc

@@ -46,8 +46,8 @@ exclude_files = {
   'test/_meta.lua',
   'test/functional/fixtures/lua/syntax_error.lua',
   'runtime/lua/vim/treesitter/_meta.lua',
-  'runtime/lua/vim/_meta/vimfn.lua',
-  'runtime/lua/vim/_meta/api.lua',
+  'runtime/lua/vim/_meta/vimfn.gen.lua',
+  'runtime/lua/vim/_meta/api.gen.lua',
   'runtime/lua/vim/re.lua',
   'runtime/lua/uv/_meta.lua',
   'runtime/lua/coxpcall.lua',

runtime/lua/vim/_meta/api.gen.lua

@@ -1,6 +1,7 @@
 --- @meta _
--- THIS FILE IS GENERATED
--- DO NOT EDIT
+--
+-- DO NOT EDIT. GENERATED BY: src/gen/gen_eval_files.lua
+--
 error('Cannot require a meta file')
 
 --- This file embeds vimdoc as the function descriptions

runtime/lua/vim/_meta/api_keysets.gen.lua

@@ -1,6 +1,7 @@
 --- @meta _
--- THIS FILE IS GENERATED
--- DO NOT EDIT
+--
+-- DO NOT EDIT. GENERATED BY: src/gen/gen_eval_files.lua
+--
 error('Cannot require a meta file')
 
 --- @class vim.api.keyset.buf_attach

runtime/lua/vim/_meta/api_keysets_extra.lua

@@ -1,4 +1,5 @@
 --- @meta _
+-- This file is NOT generated, edit it directly. See also _meta/api_keysets.gen.lua.
 error('Cannot require a meta file')
 
 --- Extra types we can't generate keysets for

runtime/lua/vim/_meta/base64.lua

@@ -1,4 +1,6 @@
 --- @meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
 
 vim.base64 = {}
 

runtime/lua/vim/_meta/builtin.lua

@@ -1,4 +1,5 @@
 ---@meta
+-- This file is NOT generated, edit it directly.
 -- luacheck: no unused args
 
 error('Cannot require a meta file')

runtime/lua/vim/_meta/builtin_types.lua

@@ -1,3 +1,7 @@
+--- @meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
+
 --- @class vim.fn.sign
 --- @field group string
 --- @field id integer

runtime/lua/vim/_meta/json.lua

@@ -1,4 +1,6 @@
 ---@meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
 
 ---@nodoc
 vim.json = {}

runtime/lua/vim/_meta/lpeg.lua

@@ -1,4 +1,5 @@
 --- @meta
+-- This file is NOT generated, edit it directly.
 error('Cannot require a meta file')
 
 -- These types were taken from https://github.com/LuaCATS/lpeg

runtime/lua/vim/_meta/misc.lua

@@ -1,4 +1,6 @@
 ---@meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
 
 -- luacheck: no unused args
 

runtime/lua/vim/_meta/mpack.lua

@@ -1,4 +1,6 @@
 --- @meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
 
 -- luacheck: no unused args
 

runtime/lua/vim/_meta/options.gen.lua

@@ -1,6 +1,7 @@
 --- @meta _
--- THIS FILE IS GENERATED
--- DO NOT EDIT
+--
+-- DO NOT EDIT. GENERATED BY: src/gen/gen_eval_files.lua
+--
 error('Cannot require a meta file')
 
 ---@class vim.bo

runtime/lua/vim/_meta/re.lua

@@ -1,4 +1,5 @@
 --- @meta
+-- This file is NOT generated, edit it directly.
 error('Cannot require a meta file')
 
 -- Documentations and Lua types for vim.re (vendored re.lua, lpeg-1.1.0)

runtime/lua/vim/_meta/regex.lua

@@ -1,4 +1,6 @@
 --- @meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
 
 -- luacheck: no unused args
 

runtime/lua/vim/_meta/spell.lua

@@ -1,4 +1,6 @@
 --- @meta
+-- This file is NOT generated, edit it directly.
+error('Cannot require a meta file')
 
 -- luacheck: no unused args
 

runtime/lua/vim/_meta/vimfn.gen.lua

@@ -1,6 +1,7 @@
 --- @meta _
--- THIS FILE IS GENERATED
--- DO NOT EDIT
+--
+-- DO NOT EDIT. GENERATED BY: src/gen/gen_eval_files.lua
+--
 error('Cannot require a meta file')
 
 --- Return the absolute value of {expr}.  When {expr} evaluates to

runtime/lua/vim/_meta/vvars.gen.lua

@@ -1,6 +1,7 @@
 --- @meta _
--- THIS FILE IS GENERATED
--- DO NOT EDIT
+--
+-- DO NOT EDIT. GENERATED BY: src/gen/gen_eval_files.lua
+--
 error('Cannot require a meta file')
 
 --- @class vim.v

runtime/lua/vim/_meta/vvars_extra.lua

@@ -1,4 +1,5 @@
 --- @meta _
+-- This file is NOT generated, edit it directly. See also _meta/vvars.gen.lua.
 error('Cannot require a meta file')
 
 --- Extra types for vim.v dictionary fields

src/gen/gen_eval_files.lua

@@ -30,29 +30,22 @@ local LUA_API_RETURN_OVERRIDES = {
 
 local LUA_META_HEADER = {
   '--- @meta _',
-  '-- THIS FILE IS GENERATED',
-  '-- DO NOT EDIT',
+  '--',
+  '-- DO NOT EDIT. GENERATED BY: src/gen/gen_eval_files.lua',
+  '--',
   "error('Cannot require a meta file')",
 }
 
-local LUA_API_META_HEADER = {
-  '--- @meta _',
-  '-- THIS FILE IS GENERATED',
-  '-- DO NOT EDIT',
-  "error('Cannot require a meta file')",
+local LUA_API_META_HEADER = vim.list_extend(vim.deepcopy(LUA_META_HEADER), {
   '',
   '--- This file embeds vimdoc as the function descriptions',
   '--- so ignore any doc related errors.',
   '--- @diagnostic disable: undefined-doc-name,luadoc-miss-symbol',
   '',
   'vim.api = {}',
-}
+})
 
-local LUA_OPTION_META_HEADER = {
-  '--- @meta _',
-  '-- THIS FILE IS GENERATED',
-  '-- DO NOT EDIT',
-  "error('Cannot require a meta file')",
+local LUA_OPTION_META_HEADER = vim.list_extend(vim.deepcopy(LUA_META_HEADER), {
   '',
   '---@class vim.bo',
   '---@field [integer] vim.bo',
@@ -61,17 +54,13 @@ local LUA_OPTION_META_HEADER = {
   '---@class vim.wo',
   '---@field [integer] vim.wo',
   'vim.wo = vim.wo',
-}
+})
 
-local LUA_VVAR_META_HEADER = {
-  '--- @meta _',
-  '-- THIS FILE IS GENERATED',
-  '-- DO NOT EDIT',
-  "error('Cannot require a meta file')",
+local LUA_VVAR_META_HEADER = vim.list_extend(vim.deepcopy(LUA_META_HEADER), {
   '',
   '--- @class vim.v',
   'vim.v = ...',
-}
+})
 
 local LUA_KEYWORDS = {
   ['and'] = true,
@@ -879,19 +868,19 @@ end
 --- @type nvim.gen_eval_files.elem[]
 local CONFIG = {
   {
-    path = 'runtime/lua/vim/_meta/vimfn.lua',
+    path = 'runtime/lua/vim/_meta/vimfn.gen.lua',
     header = LUA_META_HEADER,
     funcs = get_eval_meta,
     render = render_eval_meta,
   },
   {
-    path = 'runtime/lua/vim/_meta/api.lua',
+    path = 'runtime/lua/vim/_meta/api.gen.lua',
     header = LUA_API_META_HEADER,
     funcs = get_api_meta,
     render = render_api_meta,
   },
   {
-    path = 'runtime/lua/vim/_meta/api_keysets.lua',
+    path = 'runtime/lua/vim/_meta/api_keysets.gen.lua',
     header = LUA_META_HEADER,
     funcs = get_api_keysets_meta,
     render = render_api_keyset_meta,
@@ -943,7 +932,7 @@ local CONFIG = {
     },
   },
   {
-    path = 'runtime/lua/vim/_meta/options.lua',
+    path = 'runtime/lua/vim/_meta/options.gen.lua',
     header = LUA_OPTION_META_HEADER,
     funcs = get_option_meta,
     render = render_option_meta,
@@ -959,7 +948,7 @@ local CONFIG = {
     render = render_option_doc,
   },
   {
-    path = 'runtime/lua/vim/_meta/vvars.lua',
+    path = 'runtime/lua/vim/_meta/vvars.gen.lua',
     header = LUA_VVAR_META_HEADER,
     funcs = get_vvar_meta,
     render = render_vvar_meta,