fix: use return_overload annotations in std libs, to fix overload return type inference for functions like load, io.open, etc.

Author: efve.zff

crates/emmylua_code_analysis/resources/std/global.lua

@@ -164,8 +164,8 @@ function ipairs(t) end
 ---@param chunkname? string
 ---@param mode? std.loadmode
 ---@param env? table
----@return function? chunk
----@return string?   error_message
+---@return_overload function chunk
+---@return_overload nil, string error_message
 ---@nodiscard
 function load(chunk, chunkname, mode, env) end
 
@@ -175,8 +175,8 @@ function load(chunk, chunkname, mode, env) end
 ---@version 5.1, JIT
 ---@param text       Language<"Lua">
 ---@param chunkname? string
----@return function? chunk
----@return string?   error_message
+---@return_overload function chunk
+---@return_overload nil, string error_message
 ---@nodiscard
 function loadstring(text, chunkname) end
 
@@ -186,8 +186,8 @@ function loadstring(text, chunkname) end
 ---@param filename? string
 ---@param mode? std.loadmode
 ---@param env? table
----@return function? chunk
----@return string? error_message
+---@return_overload function chunk
+---@return_overload nil, string error_message
 function loadfile(filename, mode, env) end
 
 ---@version 5.1, JIT

crates/emmylua_code_analysis/resources/std/io.lua

@@ -74,8 +74,8 @@ function io.lines(filename, ...) end
 --- some systems to open the file in binary mode.
 ---@param filename string
 ---@param mode? iolib.OpenMode
----@return file?
----@return string? err
+---@return_overload file
+---@return_overload nil, string err
 function io.open(filename, mode) end
 
 ---
@@ -132,8 +132,8 @@ function io.type(obj) end
 ---
 --- Equivalent to `io.output():write(···)`.
 --- @param ... string | number
---- @return file?
---- @return string? err
+--- @return_overload file
+--- @return_overload nil, string err
 function io.write(...) end
 
 --- File object
@@ -148,24 +148,23 @@ local file = {}
 ---
 --- When closing a file handle created with `io.popen`, `file:close` returns the
 --- same values returned by `os.execute`.
---- @return true|nil
---- @return 'exit'|'signal'
---- @return integer
+--- @return_overload true, 'exit'|'signal', integer
+--- @return_overload nil, 'exit'|'signal', integer
 function file:close() end
 
 ---@version 5.1, JIT
 ---
 --- Closes `file`. Note that files are automatically closed when their
 --- handles are garbage collected, but that takes an unpredictable amount of
 --- time to happen.
---- @return true|nil
---- @return string? err
+--- @return_overload true
+--- @return_overload nil, string err
 function file:close() end
 
 ---
 --- Saves any written data to `file`.
---- @return true|nil
---- @return string? err
+--- @return_overload true
+--- @return_overload nil, string err
 function file:flush() end
 
 ---
@@ -234,8 +233,8 @@ function file:read(...) end
 ---@overload fun()
 ---@param whence string | 'set' | 'cur' | 'end'
 ---@param offset integer
----@return integer? pos
----@return string? err
+---@return_overload integer pos
+---@return_overload nil, string err
 function file:seek(whence, offset) end
 
 ---
@@ -261,8 +260,8 @@ function file:setvbuf(mode, size) end
 --- In case of success, this function returns `file`. Otherwise it returns
 --- **nil** plus a string describing the error.
 --- @param ... string | number
---- @return file?
---- @return string? err
+--- @return_overload file
+--- @return_overload nil, string err
 function file:write(...) end
 
 --- * `io.stderr`: Standard error.

crates/emmylua_code_analysis/resources/std/package.lua

@@ -168,8 +168,8 @@ package.searchers = {}
 ---@param path? string
 ---@param sep? string
 ---@param rep? string
----@return string? filename
----@return string? error
+---@return_overload file
+---@return_overload nil, string err
 function package.searchpath(name, path, sep, rep) end
 
 ---@version 5.1, JIT

crates/emmylua_code_analysis/resources/std/utf8.lua

@@ -78,8 +78,8 @@ function utf8.codepoint(s, i, j, lax) end
 ---@param s    string
 ---@param i?   integer
 ---@param j?   integer
----@return integer?
----@return integer? errpos
+---@return_overload integer
+---@return_overload nil, integer errpos
 ---@nodiscard
 function utf8.len(s, i, j) end
 
@@ -88,8 +88,8 @@ function utf8.len(s, i, j) end
 ---@param i?   integer
 ---@param j?   integer
 ---@param lax? boolean
----@return integer?
----@return integer? errpos
+---@return_overload integer
+---@return_overload nil, integer errpos
 ---@nodiscard
 function utf8.len(s, i, j, lax) end