Merge pull request #119 from CogentRedTester/type-annotations

Add type checking with Lua Language Server type annotations

.github/workflows/lint.yml

@@ -0,0 +1,118 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Lint
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the "master" branch
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  Build_LuaLS:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    outputs:
+      luals_version: ${{ steps.get-luaLS-version.outputs.version }}
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      - name: Get LuaLS version
+        id: get-luaLS-version
+        run: |
+          version=$(curl https://api.github.com/repos/LuaLS/lua-language-server/releases/latest | jq -r '.tag_name')
+          echo $version
+          echo "version=$version" >> $GITHUB_OUTPUT
+        shell: bash
+
+      - name: Cache Lua Language Server
+        uses: actions/cache@v4
+        id: cache
+        with:
+          key: ${{ steps.get-luaLS-version.outputs.version }}
+          path: ./luals
+
+      - uses: actions/checkout@v4
+        if: steps.cache.outputs.cache-hit != 'true'
+        with:
+          repository: LuaLS/lua-language-server
+          ref: ${{ steps.get-luaLS-version.outputs.version }}
+          path: ./luals
+
+      # Runs a single command using the runners shell
+      - name: Install Lua Language Server
+        if: steps.cache.outputs.cache-hit != 'true'
+        working-directory: ./luals
+        run: |
+          echo Running Lua Language Server build script
+          sudo apt-get update
+          sudo apt-get -y install ninja-build
+          ./make.sh
+  
+  Lint_LuaJit:
+    needs: Build_LuaLS
+    runs-on: ubuntu-latest
+    steps:
+            # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v4
+        with:
+          path: ./file-browser
+      - name: Cache Lua Language Server
+        uses: actions/cache@v4
+        id: cache
+        with:
+          key: ${{ needs.Build_LuaLS.outputs.luals_version }}
+          path: ./luals
+      - name: Run LuaLS
+        run: |
+          jq '."runtime.version" = "LuaJIT"' ./file-browser/.luarc.json > tmp.json
+          mv tmp.json ./file-browser/.luarc.json
+          ./luals/bin/lua-language-server --check=./file-browser
+
+  Lint_Lua51:
+    needs: Build_LuaLS
+    runs-on: ubuntu-latest
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v4
+        with:
+          path: ./file-browser
+      - name: Cache Lua Language Server
+        uses: actions/cache@v4
+        id: cache
+        with:
+          key: ${{ needs.Build_LuaLS.outputs.luals_version }}
+          path: ./luals
+      - name: Run LuaLS
+        run: |
+          jq '."runtime.version" = "Lua 5.1"' ./file-browser/.luarc.json > tmp.json
+          mv tmp.json ./file-browser/.luarc.json
+          ./luals/bin/lua-language-server --check=./file-browser
+
+  Lint_Lua52:
+    needs: Build_LuaLS
+    runs-on: ubuntu-latest
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v4
+        with:
+          path: ./file-browser
+      - name: Cache Lua Language Server
+        uses: actions/cache@v4
+        id: cache
+        with:
+          key: ${{ needs.Build_LuaLS.outputs.luals_version }}
+          path: ./luals
+      - name: Run LuaLS
+        run: |
+          jq '."runtime.version" = "Lua 5.2"' ./file-browser/.luarc.json > tmp.json
+          mv tmp.json ./file-browser/.luarc.json
+          ./luals/bin/lua-language-server --check=./file-browser

.gitignore

@@ -0,0 +1 @@
+.vscode

.luarc.json

@@ -0,0 +1,27 @@
+{
+    "runtime.version": "LuaJIT",
+    "runtime.path": [
+        "?.lua",
+        "?/init.lua",
+        "../../script-modules/?.lua"
+    ],
+    "diagnostics.workspaceDelay": 1000,
+    "diagnostics.groupFileStatus": {
+        "await": "Any",
+        "luadoc": "Any",
+        "type-check": "Any",
+        "unbalanced": "Any",
+        "strong": "Any"
+    },
+    "diagnostics.groupSeverity": {
+        "await": "Warning",
+        "strong": "Warning"
+    },
+    "diagnostics.severity": {
+        "missing-return": "Error!",
+        "missing-return-value": "Error!",
+        "cast-type-mismatch": "Error!",
+        "assign-type-mismatch": "Error!",
+        "global-element": "Warning!"
+    }
+}

addons/apache-browser.lua

@@ -9,6 +9,7 @@ local fb = require "file-browser"
 
 --decodes a URL address
 --this piece of code was taken from: https://stackoverflow.com/questions/20405985/lua-decodeuri-luvit/20406960#20406960
+---@type fun(s: string): string
 local decodeURI
 do
     local char, gsub, tonumber = string.char, string.gsub, tonumber
@@ -20,22 +21,32 @@ do
     end
 end
 
+---@type ParserConfig
 local apache = {
     priority = 80,
     api_version = "1.1.0"
 }
 
+---@param name string
+---@return boolean
 function apache:can_parse(name)
-    return name:find("^https?://")
+    return name:find("^https?://") ~= nil
 end
 
---send curl errors through the browser empty_text
-function apache:send_error(str)
+---Send curl errors through the browser empty_text.
+---@param str string
+---@return List
+---@return Opts
+local function send_error(str)
     return {}, {empty_text = "curl error: "..str}
 end
 
+---@async
+---@param args string[]
+---@return MPVSubprocessResult
 local function execute(args)
     msg.trace(utils.to_string(args))
+    ---@type boolean, MPVSubprocessResult
     local _, cmd = fb.get_parse_state():yield(
         mp.command_native_async({
             name = "subprocess",
@@ -48,21 +59,22 @@ local function execute(args)
     return cmd
 end
 
+---@async
 function apache:parse(directory)
     msg.verbose(directory)
 
     local test = execute({"curl", "-k", "-l", "-I", directory})
     local response = test.stdout:match("(%d%d%d [^\n\r]+)")
     if test.stdout:match("Content%-Type: ([^\r\n/]+)") ~= "text" then return nil end
-    if response ~= "200 OK" then return self:send_error(response) end
+    if response ~= "200 OK" then return send_error(response) end
 
     local html = execute({"curl", "-k", "-l", directory})
-    if html.status ~= 0 then return self:send_error(tostring(html.status))
+    if html.status ~= 0 then return send_error(tostring(html.status))
     elseif not html.stdout:find("%[PARENTDIR%]") then return nil end
 
-    html = html.stdout
+    local html_body = html.stdout
     local list = {}
-    for str in string.gmatch(html, "[^\r\n]+") do
+    for str in string.gmatch(html_body, "[^\r\n]+") do
         local valid = true
         if str:sub(1,4) ~= "<tr>" then valid = false end
 

addons/favourites.lua

@@ -4,8 +4,9 @@
 
 local mp = require "mp"
 local msg = require "mp.msg"
-local utils = require "mp.utils"
-local save_path = mp.command_native({"expand-path", "~~/script-opts/file_browser_favourites.txt"})
+
+local fb = require 'file-browser'
+local save_path = mp.command_native({"expand-path", "~~/script-opts/file_browser_favourites.txt"}) --[[@as string]]
 do
     local file = io.open(save_path, "a+")
     if not file then
@@ -15,16 +16,24 @@ do
     file:close()
 end
 
-local favourites = nil
+---@type Item[]
+local favourites = {}
+local favourites_loaded = false
+
+---@type ParserConfig
 local favs = {
     api_version = "1.4.0",
     priority = 30,
     cursor = 1
 }
 
 local use_virtual_directory = true
+
+---@type table<string,string>
 local full_paths = {}
 
+---@param str string
+---@return Item
 local function create_favourite_object(str)
     local item = {
         type = str:sub(-1) == "/" and "dir" or "file",
@@ -36,34 +45,38 @@ local function create_favourite_object(str)
     return item
 end
 
+---@param self Parser
 function favs:setup()
     self:register_root_item('Favourites/')
 end
 
 local function update_favourites()
-    favourites = {}
-
     local file = io.open(save_path, "r")
     if not file then return end
 
     for str in file:lines() do
         table.insert(favourites, create_favourite_object(str))
     end
     file:close()
+    favourites_loaded = true
 end
 
 function favs:can_parse(directory)
     return directory:find("Favourites/") == 1
 end
 
+---@async
+---@param self Parser
+---@param directory string
+---@return List?
+---@return Opts?
 function favs:parse(directory)
-    if not favourites then update_favourites() end
+    if not favourites_loaded then update_favourites() end
     if directory == "Favourites/" then
         local opts = {
             filtered = true,
             sorted = true
         }
-        if self.cursor ~= 1 then opts.selected_index = self.cursor ; self.cursor = 1 end
         return favourites, opts
     end
 
@@ -76,6 +89,7 @@ function favs:parse(directory)
         local list, opts = self:defer(full_path or "")
 
         if not list then return nil end
+        opts = opts or {}
         opts.id = self:get_id()
         if opts.directory_label then
             opts.directory_label = opts.directory_label:gsub(full_paths[name], "Favourites/"..name..'/')
@@ -94,10 +108,14 @@ function favs:parse(directory)
 
     local list, opts = self:defer(path)
     if not list then return nil end
+    opts = opts or {}
     opts.directory = opts.directory or path
     return list, opts
 end
 
+---@param path string
+---@return integer?
+---@return Item?
 local function get_favourite(path)
     for index, value in ipairs(favourites) do
         if value.path == path then return index, value end
@@ -106,14 +124,14 @@ end
 
 --update the browser with new contents of the file
 local function update_browser()
-    if favs.get_directory():find("[fF]avourites/") then
-        if favs.get_directory():find("[fF]avourites/$") then
-            local cursor = favs.get_selected_index()
-            favs.rescan()
-            favs.set_selected_index(cursor)
-            favs.redraw()
+    if fb.get_directory():find("[fF]avourites/") then
+        if fb.get_directory():find("[fF]avourites/$") then
+            local cursor = fb.get_selected_index()
+            fb.rescan()
+            fb.set_selected_index(cursor)
+            fb.redraw()
         else
-            favs.clear_cache()
+            fb.clear_cache()
         end
     end
 end
@@ -154,7 +172,7 @@ local function move_favourite(path, direction)
 end
 
 local function toggle_favourite(cmd, state, co)
-    local path = favs.get_full_path(state.list[state.selected], state.directory)
+    local path = fb.get_full_path(state.list[state.selected], state.directory)
 
     if state.directory:find("[fF]avourites/$") then remove_favourite(path)
     else add_favourite(path) end
@@ -163,15 +181,15 @@ end
 
 local function move_key(cmd, state, co)
     if not state.directory:find("[fF]avourites/") then return false end
-    local path = favs.get_full_path(state.list[state.selected], state.directory)
+    local path = fb.get_full_path(state.list[state.selected], state.directory)
 
-    local cursor = favs.get_selected_index()
+    local cursor = fb.get_selected_index()
     if cmd.name == favs:get_id().."/move_up" then
         move_favourite(path, -1)
-        favs.set_selected_index(cursor-1)
+        fb.set_selected_index(cursor-1)
     else
         move_favourite(path, 1)
-        favs.set_selected_index(cursor+1)
+        fb.set_selected_index(cursor+1)
     end
     update_browser()
 end