From 53038d2c381e79fcb2ba9c7c5b2e637e3db76f6a Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Tue, 14 Apr 2026 05:38:47 -0400
Subject: [PATCH] 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`.

(cherry picked from commit 65b40e69acbcb28c0e7ef9228f731c444a788e93)
---
 .gitattributes                                |  7 +---
 .luacheckrc                                   |  4 +-
 .../lua/vim/_meta/{api.lua => api.gen.lua}    |  5 ++-
 .../{api_keysets.lua => api_keysets.gen.lua}  |  5 ++-
 runtime/lua/vim/_meta/api_keysets_extra.lua   |  1 +
 runtime/lua/vim/_meta/base64.lua              |  2 +
 runtime/lua/vim/_meta/builtin.lua             |  1 +
 runtime/lua/vim/_meta/builtin_types.lua       |  4 ++
 runtime/lua/vim/_meta/json.lua                |  2 +
 runtime/lua/vim/_meta/lpeg.lua                |  1 +
 runtime/lua/vim/_meta/misc.lua                |  2 +
 runtime/lua/vim/_meta/mpack.lua               |  2 +
 .../_meta/{options.lua => options.gen.lua}    |  5 ++-
 runtime/lua/vim/_meta/re.lua                  |  1 +
 runtime/lua/vim/_meta/regex.lua               |  2 +
 runtime/lua/vim/_meta/spell.lua               |  2 +
 .../vim/_meta/{vimfn.lua => vimfn.gen.lua}    |  5 ++-
 .../vim/_meta/{vvars.lua => vvars.gen.lua}    |  5 ++-
 runtime/lua/vim/_meta/vvars_extra.lua         |  1 +
 src/gen/gen_eval_files.lua                    | 39 +++++++------------
 20 files changed, 54 insertions(+), 42 deletions(-)
 rename runtime/lua/vim/_meta/{api.lua => api.gen.lua} (99%)
 rename runtime/lua/vim/_meta/{api_keysets.lua => api_keysets.gen.lua} (99%)
 rename runtime/lua/vim/_meta/{options.lua => options.gen.lua} (99%)
 rename runtime/lua/vim/_meta/{vimfn.lua => vimfn.gen.lua} (99%)
 rename runtime/lua/vim/_meta/{vvars.lua => vvars.gen.lua} (99%)

diff --git a/.gitattributes b/.gitattributes
index 381fc27e80..160f11b321 100644
--- a/.gitattributes
+++ b/.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
diff --git a/.luacheckrc b/.luacheckrc
index c7f0af0b1a..cdefcbbab4 100644
--- a/.luacheckrc
+++ b/.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',
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.gen.lua
similarity index 99%
rename from runtime/lua/vim/_meta/api.lua
rename to runtime/lua/vim/_meta/api.gen.lua
index fd0387c33d..2cc2322f48 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.gen.lua
similarity index 99%
rename from runtime/lua/vim/_meta/api_keysets.lua
rename to runtime/lua/vim/_meta/api_keysets.gen.lua
index aa3f6f4001..52c7c9c615 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua
index 4a586e9d1f..3b8461892b 100644
--- a/runtime/lua/vim/_meta/api_keysets_extra.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/base64.lua b/runtime/lua/vim/_meta/base64.lua
index 895ac3334b..b164d0274f 100644
--- a/runtime/lua/vim/_meta/base64.lua
+++ b/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 = {}
 
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index de95436531..65ec0ae8ed 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/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')
diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
index 34ff38f6a4..d7081a7454 100644
--- a/runtime/lua/vim/_meta/builtin_types.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua
index 6faaa439d1..9e195cbda3 100644
--- a/runtime/lua/vim/_meta/json.lua
+++ b/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 = {}
diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index d354de95df..12582015ff 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/misc.lua b/runtime/lua/vim/_meta/misc.lua
index 87929353af..0910eb9b40 100644
--- a/runtime/lua/vim/_meta/misc.lua
+++ b/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
 
diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua
index e09c2fecef..f35dae58fb 100644
--- a/runtime/lua/vim/_meta/mpack.lua
+++ b/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
 
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.gen.lua
similarity index 99%
rename from runtime/lua/vim/_meta/options.lua
rename to runtime/lua/vim/_meta/options.gen.lua
index f8d369e7c7..cb60dd0f0e 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
index d16751fbbf..514e33c750 100644
--- a/runtime/lua/vim/_meta/re.lua
+++ b/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)
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
index 9c9cd7d29b..37521b178a 100644
--- a/runtime/lua/vim/_meta/regex.lua
+++ b/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
 
diff --git a/runtime/lua/vim/_meta/spell.lua b/runtime/lua/vim/_meta/spell.lua
index b4e3bf6ca4..fe992323ea 100644
--- a/runtime/lua/vim/_meta/spell.lua
+++ b/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
 
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.gen.lua
similarity index 99%
rename from runtime/lua/vim/_meta/vimfn.lua
rename to runtime/lua/vim/_meta/vimfn.gen.lua
index 2777995d58..5e63c82e85 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.gen.lua
similarity index 99%
rename from runtime/lua/vim/_meta/vvars.lua
rename to runtime/lua/vim/_meta/vvars.gen.lua
index c068aed005..90cece6b8c 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/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
diff --git a/runtime/lua/vim/_meta/vvars_extra.lua b/runtime/lua/vim/_meta/vvars_extra.lua
index 41dcbce966..a009cb8ca1 100644
--- a/runtime/lua/vim/_meta/vvars_extra.lua
+++ b/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
diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua
index 3df650fc0b..24de06e859 100755
--- a/src/gen/gen_eval_files.lua
+++ b/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,