add annotations for luacheck

assign-attributes.lua

@@ -79,7 +79,7 @@ local valid_args = utils.invert({
 
 
 -- ----------------------------------------------- UTILITY FUNCTIONS ------------------------------------------------ --
-local function print_yellow(text)
+function print_yellow(text)
     dfhack.color(COLOR_YELLOW)
     print(text)
     dfhack.color(-1)
@@ -146,7 +146,7 @@ function assign(attributes, unit, reset)
     reset = reset or false
 
     if type(unit) == "number" then
-        unit = df.unit.find(tonumber(unit))
+        unit = df.unit.find(tonumber(unit)) --luacheck:retype
     else
         unit = unit or dfhack.gui.getSelectedUnit(true)
     end

assign-beliefs.lua

@@ -100,7 +100,7 @@ function assign(beliefs, unit, reset)
     reset = reset or false
 
     if type(unit) == "number" then
-        unit = df.unit.find(tonumber(unit))
+        unit = df.unit.find(tonumber(unit)) --luacheck:retype
     end
     unit = unit or dfhack.gui.getSelectedUnit(true)
     if not unit then

assign-facets.lua

@@ -98,7 +98,7 @@ function assign(facets, unit, reset)
     reset = reset or false
 
     if type(unit) == "number" then
-        unit = df.unit.find(tonumber(unit))
+        unit = df.unit.find(tonumber(unit)) --luacheck:retype
     end
     unit = unit or dfhack.gui.getSelectedUnit(true)
     if not unit then

assign-goals.lua

@@ -81,7 +81,7 @@ function assign(goals, unit, reset)
     reset = reset or false
 
     if type(unit) == "number" then
-        unit = df.unit.find(tonumber(unit))
+        unit = df.unit.find(tonumber(unit)) --luacheck:retype
     end
     unit = unit or dfhack.gui.getSelectedUnit(true)
     if not unit then

assign-preferences.lua

@@ -219,8 +219,9 @@ local preference_functions = {
     -- ---------------- LIKEMATERIAL ---------------- --
     LIKEMATERIAL = function(token)
         local mat_info = dfhack.matinfo.find(token)
+        local ret = {}
         if mat_info then
-            return {
+            ret = { --luacheck:retype
                 type = df.unit_preference.T_type.LikeMaterial,
                 item_type = -1,
                 creature_id = -1,
@@ -239,8 +240,8 @@ local preference_functions = {
             }
         else
             print_yellow("WARNING: '" .. token .. "' does not seem to be a valid material token. Skipping...")
-            return {}
         end
+        return ret
     end,
     -- ---------------- LIKECREATURE ---------------- --
     LIKECREATURE = function(token)
@@ -572,11 +573,11 @@ function assign(preferences, unit, reset)
     assert(not unit or type(unit) == "number" or type(unit) == "userdata")
     assert(not reset or type(reset) == "boolean")
 
-    preferences = preferences or {}
+    local preferences = preferences or {} --as:string[][]
     reset = reset or false
 
     if type(unit) == "number" then
-        unit = df.unit.find(tonumber(unit))
+        unit = df.unit.find(tonumber(unit)) --luacheck:retype
     end
     unit = unit or dfhack.gui.getSelectedUnit(true)
     if not unit then
@@ -594,8 +595,8 @@ function assign(preferences, unit, reset)
     for preference_type, preference_tokens in pairs(preferences) do
         assert(type(preference_tokens) == "table" or type(preference_tokens) == "string")
         local funct = preference_functions[preference_type:upper()]
-        if type(preference_tokens) == "string" then
-            preference_tokens = {preference_tokens} --retype string as table with only one item
+        if type(preference_tokens) == "string" then --luacheck:skip
+            preference_tokens = {preference_tokens}
         end
         for _, token in ipairs(preference_tokens) do
             assert(type(token) == "string")

assign-profile.lua

@@ -107,6 +107,7 @@ end
 ---             See the modules documentation for more details.
 ---   :unit: a valid unit id, a df.unit object, or nil. If nil, the currently selected unit will be targeted.
 ---   :reset: nil, or a table value/boolean. See this script documentation for valid values.
+--luacheck: in=string[],df.unit,bool[]
 function apply_profile(profile, unit, reset_table)
     assert(not profile or type(profile) == "table")
     assert(not unit or type(unit) == "number" or type(unit) == "userdata")
@@ -132,11 +133,12 @@ end
 --- The filename must begin with a slash and must be a relative path starting from the root DF
 --- directory and ending at the desired file.
 --- Return the parsed profile as a table.
+--luacheck: in=string,string
 function load_profile(profile_name, filename)
     assert(profile_name ~= nil)
 
     local json_file = string.format("%s%s", dfhack.getDFPath(), filename or default_filename)
-    local profiles
+    local profiles = {} --as:string[][]
     if dfhack.filesystem.isfile(json_file) then
         profiles = json.decode_file(json_file)
     else

assign-skills.lua

@@ -96,7 +96,7 @@ function assign(skills, unit, reset)
     reset = reset or false
 
     if type(unit) == "number" then
-        unit = df.unit.find(tonumber(unit))
+        unit = df.unit.find(tonumber(unit)) --luacheck:retype
     end
     unit = unit or dfhack.gui.getSelectedUnit(true)
     if not unit then

combat-harden.lua

@@ -79,7 +79,7 @@ function main(...)
         value = tonumber(args.value) or 100
     end
 
-    local unitsList = {}
+    local unitsList = {} --as:df.unit[]
 
     if not args.all and not args.citizens then
         -- Assume trying to target a unit

deep-embark.lua

@@ -89,7 +89,7 @@ function getFeatureID(cavernType)
 end
 
 function getFeatureBlocks(featureID)
-  local featureBlocks = {}
+  local featureBlocks = {} --as:number[]
   for i,block in ipairs(df.global.world.map.map_blocks) do
     if block.global_feature == featureID and block.local_feature == -1 then
       table.insert(featureBlocks, i)
@@ -122,7 +122,7 @@ function isValidTiletype(tiletype)
 end
 
 function getValidEmbarkTiles(block)
-  local validTiles = {}
+  local validTiles = {} --as:{_type:table,x:number,y:number,z:number}[]
   for xi = 0,15 do
     for yi = 0,15 do
       if block.designation[xi][yi].flow_size == 0
@@ -230,7 +230,7 @@ function moveEmbarkStuff(selectedBlock, embarkTiles)
 
 -- Move wagon contents:
   local wagonFound = false
-  for _, wagon in ipairs(df.global.world.buildings.other.WAGON) do
+  for _, wagon in ipairs(df.global.world.buildings.other.WAGON) do --as:df.building_wagonst
     if wagon.age == 0 then -- just in case there's an older wagon present for some reason
       local contained = wagon.contained_items
       for i = #contained-1, 0, -1 do

dorf_tables.lua

@@ -21,6 +21,7 @@ print("Loading data tables..")
 
 -- p denotes probability, always.
 local O = 0
+--luacheck:global
 job_distributions = {
     Thresholds      = { 7,  14, 21, 28, 30, 35, 42, 49, 56, 63, 70, 77, 80, 110, 1000 }, --Don't touch unless you wanna recalculate the distributions,
     _Grunt          = { O,  1,  2,  O,  O,  1,  2,  O,  4,  1,  1,  4,  O,  10,  880; cur = 0; max = nil },
@@ -74,6 +75,7 @@ Stat Rolling:
 
 
 --probability is used for generating all dwarf stats, some jobs include dorf_types which will upgrade particular stats
+--luacheck:global
 attrib_levels = { -- prob,      avg,    std deviation
     incompetent =   {p=0.01,    100,    20},
     verybad =       {p=0.02,    250,    25},
@@ -98,6 +100,7 @@ dorf_jobs = {
     and also the probability that the profession will be applied during the algorithm's execution.
 }
 --]]
+--luacheck:global
 jobs = {
     _Grunt = {
         req={'RECRUIT'}, max={1988},
@@ -183,6 +186,7 @@ jobs = {
         types={'genius3','intuitive2','leader'}}
 }
 
+--luacheck:global
 professions = {
 --Basic Dwarfing
     MINER =             { skills = {MINING=3} },
@@ -288,6 +292,7 @@ professions = {
 }
 
 --probability is used for randomly applying types to any and all dwarves
+--luacheck:global
 types = {
     resilient1 = {
         p = 0.2,

extinguish.lua

@@ -76,6 +76,7 @@ function extinguishContaminant(spatter)
 end
 
 function extinguishItem(item)
+  local item = item --as:df.item_actual
   if item.flags.on_fire then
     item.flags.on_fire = false
     item.temperature.whole = 10050
@@ -172,7 +173,7 @@ if not dfhack_flags.module then
     extinguishAll()
   elseif args.location then
     if dfhack.maps.isValidTilePos(args.location[1],args.location[2],args.location[3]) then
-      extinguishLocation(args.location[1],args.location[2],args.location[3])
+      extinguishLocation(tonumber(args.location[1]), tonumber(args.location[2]), tonumber(args.location[3]))
     else
       qerror("Invalid location coordinates!")
     end

forget-dead-body.lua

@@ -11,7 +11,7 @@ Removes emotions associated with seeing a dead body.
 
 local utils = require 'utils'
 
-validArgs = utils.invert({
+local validArgs = utils.invert({
     'help',
     'all',
 })

full-heal.lua

@@ -53,7 +53,7 @@ end
 
 function isCitizen(unit)
 --  required as dfhack.units.isCitizen() returns false for dead units
-    local hf = unit.hist_figure_id ~= -1 and df.historical_figure.find(unit.hist_figure_id)
+    local hf = df.historical_figure.find(unit.hist_figure_id)
     if not hf then
         return false
     end
@@ -290,6 +290,7 @@ if not dfhack_flags.module then
         if args.unit then
             unit = df.unit.find(tonumber(args.unit))
         elseif df.item_corpsest:is_instance(item) then
+            local item = item --as:df.item_corpsest
             unit = df.unit.find(item.unit_id)
         else
             unit = dfhack.gui.getSelectedUnit()

linger.lua

@@ -41,9 +41,9 @@ function getHistoricalSlayer(unit)
 
   local deathEvents = df.global.world.history.events_death
   for i = #deathEvents-1,0,-1 do
-    if deathEvents[i].victim_hf == unit.hist_figure_id then
-      local slayerHistFig = deathEvents[i].slayer_hf ~= -1 and df.historical_figure.find(deathEvents[i].slayer_hf)
-      return slayerHistFig
+    local event = deathEvents[i] --as:df.history_event_hist_figure_diedst
+    if event.victim_hf == unit.hist_figure_id then
+      return df.historical_figure.find(event.slayer_hf)
     end
   end
 end

modtools/create-unit.lua

@@ -117,7 +117,7 @@ end
 function createUnitBase(...)
   local old_gametype = df.global.gametype
   local old_mode = df.global.ui.main.mode
-  local old_popups = {}
+  local old_popups = {} --as:df.popup_message[]
   for _, popup in pairs(df.global.world.status.popups) do
     table.insert(old_popups, popup)
   end
@@ -166,37 +166,37 @@ function createUnitInner(race_id, caste_id, caste_id_choices, pos, age, domestic
 
   local equipment = arenaSpawn.equipment
 
-  local old_item_types = {}
+  local old_item_types = {} --as:df.item_type[]
   for _, item_type in pairs(equipment.item_types) do
     table.insert(old_item_types, item_type)
   end
   equipment.item_types:resize(0)
 
-  local old_item_subtypes = {}
+  local old_item_subtypes = {} --as:number[]
   for _, item_subtype in pairs(equipment.item_subtypes) do
     table.insert(old_item_subtypes, item_subtype)
   end
   equipment.item_subtypes:resize(0)
 
-  local old_item_mat_types = {}
+  local old_item_mat_types = {} --as:number[]
   for _, item_mat_type in pairs(equipment.item_materials.mat_type) do
     table.insert(old_item_mat_types, item_mat_type)
   end
   equipment.item_materials.mat_type:resize(0)
 
-  local old_item_mat_indexes = {}
+  local old_item_mat_indexes = {} --as:number[]
   for _, item_mat_index in pairs(equipment.item_materials.mat_index) do
     table.insert(old_item_mat_indexes, item_mat_index)
   end
   equipment.item_materials.mat_index:resize(0)
 
-  local old_item_counts = {}
+  local old_item_counts = {} --as:number[]
   for _, item_count in pairs(equipment.item_counts) do
     table.insert(old_item_counts, item_count)
   end
   equipment.item_counts:resize(0)
 
-  local old_skill_levels = {}
+  local old_skill_levels = {} --as:number[]
   for k, skill_level in ipairs(equipment.skill_levels) do
     table.insert(old_skill_levels, skill_level)
     equipment.skill_levels[k] = 0
@@ -303,7 +303,7 @@ function getRaceCasteIDs(raceStr, casteStr)
   end
 
   local casteIndex
-  local caste_id_choices = {}
+  local caste_id_choices = {} --as:number[]
   if casteStr then
     for i,c in ipairs(race.caste) do
       if c.caste_id == casteStr then
@@ -509,7 +509,7 @@ function nameUnit(unit, entityRawName)
   if unit.status.current_soul then
     unit.status.current_soul.name:assign(name)
   end
-  local hf = unit.hist_figure_id ~= -1 and df.historical_figure.find(unit.hist_figure_id)
+  local hf = df.historical_figure.find(unit.hist_figure_id)
   if hf then
     hf.name:assign(name)
   end
@@ -551,7 +551,7 @@ function setAge(unit, age)
 --  Shifts the unit's birth and death dates to match the specified age.
 --  Also checks for [BABY] and [CHILD] tokens and turns the unit into a baby/child if age-appropriate.
 
-  local hf = unit.hist_figure_id ~= -1 and df.historical_figure.find(unit.hist_figure_id)
+  local hf = df.historical_figure.find(unit.hist_figure_id)
 
   if age then
     if not tonumber(age) or age < 0 then -- this check is repeated for the sake of module usage
@@ -749,6 +749,7 @@ elseif args.civId and tonumber(args.civId) then
   civ_id = tonumber(args.civId)
 end
 
+local group_id
 if args.setUnitToFort or args.groupId == '\\LOCAL' then
   if not isFortressMode then
     qerror("The LOCAL group cannot be specified outside of Fortress mode!")

open-legends.lua

@@ -62,6 +62,7 @@ function Wrapper:onInput(keys)
 end
 
 function show_screen()
+    local old_view = dfhack.gui.getCurViewscreen(true)
     local ok, err = pcall(function()
         dfhack.screen.show(df.viewscreen_legendsst:new())
         Wrapper():show()

points.lua

@@ -14,6 +14,7 @@ if dfhack.isWorldLoaded() then
     df.global.world.worldgen.worldgen_parms.embark_points = tonumber(...)
     local scr = dfhack.gui.getCurViewscreen()
     if df.viewscreen_setupdwarfgamest:is_instance(scr) then
+        local scr = scr --as:df.viewscreen_setupdwarfgamest
         scr.points_remaining = tonumber(...)
     end
 else

rejuvenate.lua

@@ -42,7 +42,7 @@ end
 
 function main(args)
     local current_year, newbirthyear
-    local units = {}
+    local units = {} --as:df.unit[]
     if args.all then
         for _, u in ipairs(df.global.world.units.all) do
             if dfhack.units.isCitizen(u) then