feat(gen_lsp.lua): validate CLI args #26514

- Improve CLI argument parsing, rejects invalid argument and commands as
  early as possible. Also prints USAGE in the command line.
- No longer allows `--<outfile>`, use `--out <outfile>` instead.
- Print a little bit of verbose messages to better know what's going on
  rather than remaining silent at all times.
- Add type annotation `gen_lsp._opt` to avoid type warnings.

runtime/lua/vim/lsp/_meta/protocol.lua

@@ -1,7 +1,7 @@
 --[[
 This file is autogenerated from scripts/gen_lsp.lua
 Regenerate:
-nvim -l scripts/gen_lsp.lua gen --version 3.18 --runtime/lua/vim/lsp/_meta/protocol.lua
+nvim -l scripts/gen_lsp.lua gen --version 3.18 --out runtime/lua/vim/lsp/_meta/protocol.lua
 --]]
 
 ---@meta

scripts/gen_lsp.lua

@@ -1,11 +1,15 @@
---[[
-Generates lua-ls annotations for lsp
+-- Generates lua-ls annotations for lsp.
+
+local USAGE = [[
+Generates lua-ls annotations for lsp.
+
 USAGE:
-nvim -l scripts/gen_lsp.lua gen  # this will overwrite runtime/lua/vim/lsp/_meta/protocol.lua
-nvim -l scripts/gen_lsp.lua gen --version 3.18 --build/new_lsp_types.lua
+nvim -l scripts/gen_lsp.lua gen  # by default, this will overwrite runtime/lua/vim/lsp/_meta/protocol.lua
 nvim -l scripts/gen_lsp.lua gen --version 3.18 --out runtime/lua/vim/lsp/_meta/protocol.lua
 nvim -l scripts/gen_lsp.lua gen --version 3.18 --methods
---]]
+]]
+
+local DEFAULT_LSP_VERSION = '3.18'
 
 local M = {}
 
@@ -14,15 +18,18 @@ local function tofile(fname, text)
   if not f then
     error(('failed to write: %s'):format(f))
   else
+    print(('Written to: %s'):format(fname))
     f:write(text)
     f:close()
   end
 end
 
+---@param opt gen_lsp._opt
 local function read_json(opt)
   local uri = 'https://raw.githubusercontent.com/microsoft/language-server-protocol/gh-pages/_specifications/lsp/'
     .. opt.version
     .. '/metaModel/metaModel.json'
+  print('Reading ' .. uri)
 
   local res = vim.system({ 'curl', '--no-progress-meter', uri, '-o', '-' }):wait()
   if res.code ~= 0 or (res.stdout or ''):len() < 999 then
@@ -99,19 +106,30 @@ return protocol
   vim.cmd.write()
 end
 
+---@class gen_lsp._opt
+---@field output_file string
+---@field version string
+---@field methods boolean
+
+---@param opt gen_lsp._opt
 function M.gen(opt)
-  local protocol = read_json(opt)
+  local protocol = read_json(opt) --- @type table
 
   if opt.methods then
     gen_methods(protocol)
   end
 
   local output = {
-    '--[[',
+    '--' .. '[[',
     'This file is autogenerated from scripts/gen_lsp.lua',
     'Regenerate:',
-    [=[nvim -l scripts/gen_lsp.lua gen --version 3.18 --runtime/lua/vim/lsp/_meta/protocol.lua]=],
-    '--]]',
+    ([=[nvim -l scripts/gen_lsp.lua gen --version %s --out runtime/lua/vim/lsp/_meta/protocol.lua]=]):format(
+      DEFAULT_LSP_VERSION
+    ),
+    '--' .. ']]',
+    '',
+    '---@meta',
+    "error('Cannot require a meta file')",
     '',
     '---@alias lsp.null nil',
     '---@alias uinteger integer',
@@ -265,26 +283,39 @@ end
 
 local opt = {
   output_file = 'runtime/lua/vim/lsp/_meta/protocol.lua',
-  version = nil,
-  methods = nil,
+  version = DEFAULT_LSP_VERSION,
+  methods = false,
 }
 
-for i = 1, #_G.arg do
+local command = nil
+local i = 1
+while i <= #_G.arg do
   if _G.arg[i] == '--out' then
-    opt.output_file = _G.arg[i + 1]
+    opt.output_file = assert(_G.arg[i + 1], '--out <outfile> needed')
+    i = i + 1
   elseif _G.arg[i] == '--version' then
-    opt.version = _G.arg[i + 1]
+    opt.version = assert(_G.arg[i + 1], '--version <version> needed')
+    i = i + 1
   elseif _G.arg[i] == '--methods' then
     opt.methods = true
-  elseif vim.startswith(_G.arg[i], '--') then
-    opt.output_file = _G.arg[i]:sub(3)
+  elseif vim.startswith(_G.arg[i], '-') then
+    error('Unrecognized args: ' .. _G.arg[i])
+  else
+    if command then
+      error('More than one command was given: ' .. _G.arg[i])
+    else
+      command = _G.arg[i]
+    end
   end
+  i = i + 1
 end
 
-for _, a in ipairs(arg) do
-  if M[a] then
-    M[a](opt)
-  end
+if not command then
+  print(USAGE)
+elseif M[command] then
+  M[command](opt) -- see M.gen()
+else
+  error('Unknown command: ' .. command)
 end
 
 return M