luals annotations

cached-configs/run.lua

@@ -11,6 +11,12 @@ local function merge(table, value)
     end
 end
 
+---@class CacheFile
+---@field subset string[]
+---@field cache_file string
+---@field is_fallback_from_pypp boolean
+
+---@param subset string[]
 local function register_cache_file_pypp(subset)
     table.sort(subset)
     local cache_file = table.concat(subset, "+")
@@ -49,11 +55,13 @@ register_cache_file_pypp {"pycoalprocessing", "pyfusionenergy", "pyindustry", "p
 
 local union_of_all_subsets = {}
 for _, cache_file_info in pairs(pypp_registered_cache_files) do
+    ---@cast cache_file_info CacheFile
     for _, mod in pairs(cache_file_info.subset) do
         union_of_all_subsets[mod] = 1
     end
 end
 union_of_all_subsets = table.keys(union_of_all_subsets)
+---@diagnostic disable-next-line: return-type-mismatch
 local recognized_enabled_mods = table.filter(union_of_all_subsets, function(potential_mod) return mods[potential_mod] end)
 table.sort(recognized_enabled_mods)
 
@@ -62,12 +70,15 @@ if #recognized_enabled_mods == 0 then
     return
 end
 
+---@param left CacheFile
+---@param right CacheFile
 local function can_left_replace_fallback_right(left, right)
     return not left.is_fallback_from_pypp and right.is_fallback_from_pypp
 end
 
-local best_cache_file = nil
+local best_cache_file = nil --[[@as CacheFile]]
 for _, cache_file_info in pairs(pypp_registered_cache_files) do
+    ---@cast cache_file_info CacheFile
     local subset = cache_file_info.subset
     if #subset == #recognized_enabled_mods then
         local is_applicable = true

lib/data-stage.lua

@@ -259,7 +259,7 @@ end
 
 ---Returns an iterator through all data.raw categories of a given supertype.
 ---@param parent_type string
----@return function<string, table>
+---@return fun():{[defines.prototypes]: table}
 function py.iter_prototype_categories(parent_type)
     local types = defines.prototypes[parent_type]
     local child_type_name, value
@@ -369,9 +369,9 @@ py.add_corner_icon_to_recipe = function(recipe, corner)
     elseif recipe.results and table_size(recipe.results) >= 1 then
         result = recipe.results[1]
         if result.type == "fluid" then
-            result = FLUID(result.name)
+            result = FLUID(result.name) --[[@as data.FluidPrototype]]
         else
-            result = ITEM(result.name)
+            result = ITEM(result.name) --[[@as data.ItemPrototype]]
         end
     end
 

lib/metas/entity.lua

@@ -3,7 +3,7 @@ local collision_mask_util = require "__core__/lualib/collision-mask-util"
 local entity_types = defines.prototypes.entity
 
 ---@class data.EntityPrototype
----@field public standardize fun(self: data.EntityPrototype): data.EntityPrototype, boolean
+---@field public standardize fun(self: data.EntityPrototype): data.EntityPrototype
 ---@field public add_flag fun(self: data.EntityPrototype, flag: string): data.EntityPrototype, boolean
 ---@field public remove_flag fun(self: data.EntityPrototype, flag: string): data.EntityPrototype, boolean
 ---@field public has_flag fun(self: data.EntityPrototype, flag: string): boolean
@@ -12,8 +12,9 @@ ENTITY = setmetatable({}, {
     __call = function(self, entity)
         local etype = type(entity)
         if etype == "string" then
-            for ptype in py.iter_prototype_categories("entity") do
-                local result = data.raw[ptype][entity]
+            ---@cast entity any somehow this works but string doesnt
+            for _, pdata in py.iter_prototype_categories("entity") do
+                local result = pdata[entity]
                 if result then return result:standardize() end
             end
         elseif etype == "table" then
@@ -28,8 +29,8 @@ ENTITY = setmetatable({}, {
         error("Entity " .. tostring(entity) .. " does not exist")
     end,
     __index = function(self, entity_name)
-        for ptype in pairs(defines.prototypes.entity) do
-            local result = data.raw[ptype][entity_name]
+        for _, pdata in py.iter_prototype_categories("entity") do
+            local result = pdata[entity_name]
             if result then return result:standardize() end
         end
         return nil

lib/metas/item.lua

@@ -10,6 +10,7 @@ ITEM = setmetatable({}, {
     __call = function(self, item)
         local itype = type(item)
         if itype == "string" then
+            ---@cast item any somehow this works but string doesnt
             for _, pdata in py.iter_prototype_categories("item") do
                 local result = pdata[item]
                 if result then return result end

lib/metas/recipe.lua

@@ -482,7 +482,7 @@ end
 --- <br /> Check https://lua-api.factorio.com/latest/prototypes/RecipePrototype.html#main_product for more details
 ---@param self data.RecipePrototype
 ---@param allow_multi_product boolean
----@return data.ItemPrototype|data.FluidPrototype
+---@return data.ItemPrototype|data.FluidPrototype?
 metas.get_main_product = function(self, allow_multi_product)
     self:standardize()
     local target, target_type = self.main_product, "item"

lib/metas/technology.lua

@@ -1,10 +1,10 @@
 ---@class data.TechnologyPrototype
 ---@field public standardize fun(): data.TechnologyPrototype
----@field public add_prereq fun(self, prereq_technology_name: data.TechnologyID): data.TechnologyPrototype
----@field public remove_prereq fun(self, prereq_technology_name: data.TechnologyID): data.TechnologyPrototype
----@field public replace_prereq fun(self, old: data.TechnologyID, new: data.TechnologyID): data.TechnologyPrototype
----@field public remove_pack fun(self, science_pack_name: data.ItemID): data.TechnologyPrototype
----@field public add_pack fun(self, science_pack_name: data.ItemID): data.TechnologyPrototype
+---@field public add_prereq fun(self, prereq_technology_name: data.TechnologyID): data.TechnologyPrototype, boolean
+---@field public remove_prereq fun(self, prereq_technology_name: data.TechnologyID): data.TechnologyPrototype, boolean
+---@field public replace_prereq fun(self, old: data.TechnologyID, new: data.TechnologyID): data.TechnologyPrototype, boolean
+---@field public remove_pack fun(self, science_pack_name: data.ItemID): data.TechnologyPrototype, boolean
+---@field public add_pack fun(self, science_pack_name: data.ItemID): data.TechnologyPrototype, boolean
 TECHNOLOGY = setmetatable(data.raw.technology, {
     ---@param technology data.TechnologyPrototype
     __call = function(self, technology)

lib/table.lua

@@ -15,9 +15,9 @@ end
 ---@param tbl table
 ---@param f (fun(v: any, k: number, ...: any): number|nil)
 ---@param ... any
----@return table
+---@return number
 table.sum = function(tbl, f, ...)
-    local f = f or function(v, k, ...)
+    f = f or function(v, k, ...)
         return v
     end
     local result = 0
@@ -68,7 +68,7 @@ end
 
 ---Returns true if all elements in the table pass the test implemented by the provided function.
 ---@param tbl table
----@param f fun(v: any, k: any, ...: any): any
+---@param f any|fun(v: any, k: any, ...: any): any
 ---@param ... any
 ---@return boolean
 ---@overload fun(tbl: table, v: any): boolean
@@ -223,7 +223,7 @@ end
 -- @param tbl any[]
 -- @param tbl2 any[]
 table.extend = function(tbl, tbl2)
-    local tbl = table.deepcopy(tbl)
+    tbl = table.deepcopy(tbl)
 
     for _, v in pairs(tbl2) do
         table.insert(tbl, v)

lib/vector.lua

@@ -9,11 +9,11 @@
 ---@field rotate fun(self, angle: number): Pyvector -- rotate the vector around the z axis (angle in radians)
 ---@field is_vector fun(self): boolean
 ---@field new fun(x: {x: number, y: number, z: number} | number?, y: number?, z: number?): Pyvector -- create new vector from table or 3 numbers
----@operator add(): Pyvector
----@operator sub(): Pyvector
----@operator mul(): Pyvector
----@operator div(): Pyvector
----@operator unm(): Pyvector
+---@operator add(Pyvector): Pyvector
+---@operator sub(Pyvector): Pyvector
+---@operator mul(Pyvector): Pyvector
+---@operator div(Pyvector): Pyvector
+---@operator unm(Pyvector): Pyvector
 py.vector = {
     __add = function(self, v)
         return py.vector.new(self.x + v.x, self.y + v.y, self.z + (v.z or 0))

prototypes/config.lua

@@ -34,6 +34,16 @@ local config = {
     SCIENCE_PACK_INDEX = {}
 }
 
+---@cast config.PY_GRAPHICS_MODS {[string]: boolean}
+---@cast config.PYMODS string[]
+---@cast config.TC_SCIENCE_PACK_COUNTS_PER_LEVEL {[string]: uint[]}
+---@cast config.TC_TECH_INGREDIENTS_PER_LEVEL string[]
+---@cast config.TC_MIL_SCIENCE_IS_PROGRESSION_PACK string[]
+---@cast config.TC_MIL_SCIENCE_PACK_COUNT_PER_LEVEL string[]
+---@cast config.NON_PRODDABLE_ITEMS {[data.ItemID]: boolean}
+---@cast config.SCIENCE_PACKS string[]
+---@cast config.SCIENCE_PACK_INDEX {[data.ItemID]: uint}
+
 if mods.pystellarexpedition then
     config.SCIENCE_PACKS = {
         "automation-science-pack",

prototypes/next-upgrades.lua

@@ -32,7 +32,7 @@ local function check_for_valid_minable_properties(entity)
     if not minable_result then return false end
     if minable_result ~= entity.name then return false end
 
-    minable_result = ITEM(minable_result)
+    minable_result = ITEM(minable_result) --[[@as data.ItemPrototype]]
     if not minable_result then return false end
     if minable_result.hidden then return false end