Fix usages of global variables

- Lint references to unknown fields of modules, excluding the keys and
   colours modules. This caught several silly errors in our stub files,
   but nothing else.
 - Lint on using unknown globals. This highlighted a couple of really
   silly mistakes. Fixes #427.
 - Add documentation for fs.attributes, fs.getCapacity and pocket, as
   they were not defined before.

Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>

doc/stub/fs.lua

@@ -19,6 +19,36 @@ function getFreeSpace(path) end
 function find(pattern) end
 function getDir(path) end
 
+--- Get the capacity of the drive at the given path.
+--
+-- This may be used in conjunction with @{getFreeSpace} to determine what
+-- percentage of this drive has been used.
+--
+-- @tparam string path The path of the drive to get.
+-- @treturn number This drive's capacity. This will be 0 for "read-only" drives,
+-- such as the ROM or treasure disks.
+function getCapacity(path) end
+
+--- Get attributes about a specific file or folder.
+--
+-- The returned attributes table contains information about the size of the
+-- file, whether it is a directory, and when it was created and last modified.
+--
+-- The creation and modification times are given as the number of milliseconds
+-- since the UNIX epoch. This may be given to @{os.date} in order to convert it
+-- to more usable form.
+--
+-- @tparam string path The path to get attributes for.
+-- @treturn { size = number, isDir = boolean, created = number, modified = number }
+-- The resulting attributes.
+-- @throws If the path does not exist.
+-- @see getSize If you only care about the file's size.
+-- @see isDir If you only care whether a path is a directory or not.
+function attributes(path) end
+
+-- Defined in bios.lua
+function complete(sPath, sLocation, bIncludeFiles, bIncludeDirs) end
+
 --- A file handle which can be read from.
 --
 -- @type ReadHandle

doc/stub/os.lua

@@ -15,3 +15,10 @@ function cancelTimer(id) end
 function cancelAlarm(id) end
 function epoch(timezone) end
 function date(format, time) end
+
+-- Defined in bios.lua
+function loadAPI(path) end
+function pullEvent(filter) end
+function pullEventRaw(filter) end
+function version() end
+function run(env, path, ...) end

doc/stub/pocket.lua

@@ -0,0 +1,28 @@
+--[[-
+Control the current pocket computer, adding or removing upgrades.
+
+This API is only available on pocket computers. As such, you may use its
+presence to determine what kind of computer you are using:
+
+```lua
+if pocket then
+  print("On a pocket computer")
+else
+  print("On something else")
+end
+```
+]]
+
+--- Search the player's inventory for another upgrade, replacing the existing
+-- one with that item if found.
+--
+-- This inventory search starts from the player's currently selected slot,
+-- allowing you to prioritise upgrades.
+--
+-- @throws If an upgrade cannot be found.
+function equipBack() end
+
+--- Remove the pocket computer's current upgrade.
+--
+-- @throws If this pocket computer does not currently have an upgrade.
+function unequipBack() end

doc/stub/redstone.lua

@@ -11,4 +11,4 @@ setAnalogueOutput = setAnalogOutput
 function getAnalogOutput(sid) end
 getAnalogueOutput = getAnalogOutput
 function getAnalogInput(side) end
-getAnalogueInput = getAnaloguInput
+getAnalogueInput = getAnalogInput

doc/stub/term.lua

@@ -15,14 +15,14 @@ isColor = isColour
 function getTextColour() end
 getTextColor = getTextColor
 function getBackgroundColour() end
-getBackgroundColour = getBackgroundColour
+getBackgroundColor = getBackgroundColour
 function blit(text, text_colours, background_colours) end
 function setPaletteColour(colour, ...) end
-setPaletteColour = setPaletteColour
+setPaletteColor = setPaletteColour
 function getPaletteColour(colour, ...) end
-getPaletteColour = getPaletteColour
+getPaletteColor = getPaletteColour
 function nativePaletteColour(colour) end
-nativePaletteColour = nativePaletteColour
+nativePaletteColor = nativePaletteColour
 
 --- @type Redirect
 local Redirect = {}

illuaminate.sexp

@@ -33,17 +33,27 @@
 
     ;; It's useful to name arguments for documentation, so we allow this. It'd
     ;; be good to find a compromise in the future, but this works for now.
-    -var:unused-arg
+    -var:unused-arg)
 
-    ;; Some APIS (keys, colour and os mainly) are incomplete right now.
-    -var:unresolved-member)
   (lint
     (bracket-spaces
       (call no-space)
       (function-args no-space)
       (parens no-space)
       (table space)
-      (index no-space))))
+      (index no-space))
+
+    ;; colours imports from colors, and we don't handle that right now.
+    ;; keys is entirely dynamic, so we skip it.
+    (dynamic-modules colours keys)
+
+    (globals
+      :max
+      _CC_DEFAULT_SETTINGS
+      _CC_DISABLE_LUA51_FEATURES
+      ;; Ideally we'd pick these up from bios.lua, but illuaminate currently
+      ;; isn't smart enough.
+      sleep write printError read rs)))
 
 ;; We disable the unused global linter in bios.lua and the APIs. In the future
 ;; hopefully we'll get illuaminate to handle this.
@@ -82,3 +92,9 @@
    /src/main/resources/*/computercraft/lua/rom/programs/advanced/multishell.lua
    /src/main/resources/*/computercraft/lua/rom/programs/shell.lua)
   (linters -doc:unresolved-reference))
+
+(at /src/test/resources/test-rom
+  (lint
+    (globals
+      :max sleep write
+      cct_test describe expect howlci fail it pending stub)))

src/main/resources/assets/computercraft/lua/rom/apis/rednet.lua

@@ -334,7 +334,11 @@ end
 
 local bRunning = false
 
---- @local
+--- Listen for modem messages and converts them into rednet messages, which may
+-- then be @{receive|received}.
+--
+-- This is automatically started in the background on computer startup, and
+-- should not be called manually.
 function run()
     if bRunning then
         error("rednet is already running", 2)

src/main/resources/assets/computercraft/lua/rom/apis/settings.lua

@@ -207,7 +207,7 @@ function load(sPath)
     for k, v in pairs(tFile) do
         local ty_v = type(k)
         if type(k) == "string" and (ty_v == "string" or ty_v == "number" or ty_v == "boolean" or ty_v == "table") then
-            local opt = details[name]
+            local opt = details[k]
             if not opt or not opt.type or ty_v == opt.type then
                 set_value(k, v)
             end

src/main/resources/assets/computercraft/lua/rom/apis/turtle/turtle.lua

@@ -5,7 +5,12 @@
 if not turtle then
     error("Cannot load turtle API on computer", 2)
 end
-native = turtle.native or turtle --- @local
+
+--- The builtin turtle API, without any generated helper functions.
+--
+-- Generally you should not need to use this table - it only exists for
+-- backwards compatibility reasons.
+native = turtle.native or turtle
 
 local function addCraftMethod(object)
     if peripheral.getType("left") == "workbench" then

src/main/resources/assets/computercraft/lua/rom/modules/main/cc/pretty.lua

@@ -384,7 +384,7 @@ local function pretty_impl(obj, tracking)
         end
 
         tracking[obj] = nil
-        return group(concat(obrace, nest(2, concat(table.unpack(doc, 1, n))), space_line, cbrace))
+        return group(concat(obrace, nest(2, concat(table.unpack(doc, 1, doc.n))), space_line, cbrace))
     end
 end
 

src/main/resources/assets/computercraft/lua/rom/programs/shell.lua

@@ -46,7 +46,7 @@ local function createShellEnv(sDir)
     package.path = "?;?.lua;?/init.lua;/rom/modules/main/?;/rom/modules/main/?.lua;/rom/modules/main/?/init.lua"
     if turtle then
         package.path = package.path .. ";/rom/modules/turtle/?;/rom/modules/turtle/?.lua;/rom/modules/turtle/?/init.lua"
-    elseif command then
+    elseif commands then
         package.path = package.path .. ";/rom/modules/command/?;/rom/modules/command/?.lua;/rom/modules/command/?/init.lua"
     end
     package.config = "/\n;\n?\n!\n-"

src/main/resources/assets/computercraft/lua/rom/programs/turtle/dance.lua

@@ -94,7 +94,7 @@ print("Press any key to stop the groove")
 
 parallel.waitForAny(
     function()
-        while not bEnd do
+        while true do
             local _, key = os.pullEvent("key")
             if key ~= keys.escape then
                 return