ci: lua language server and Makefile (#2546)

* ci: add lls-check

* ci: add lls-check to ci.yml

* ci: download lua-language-server binary

* ci: download lua-language-server binary

* ci: dummy failure to test

* Revert "ci: dummy failure to test"

This reverts commit 2bc43bad430209e32a5049a16c56710c4f6e2f7b.

* ci: ignore lls-out

* ci: better name

* ci: shellcheck nits

* ci: add luals libs and tidy

* ci: tidy

* ci: add neovim 0.9.4

* ci: add ci neovim 0.9.4 to lib path

* ci: dummy failure to test

* Revert "ci: dummy failure to test"

This reverts commit 45987335d81ec65fecc6636b339671a9a9fcdd97.

* Revert "ci: add ci neovim 0.9.4 to lib path"

This reverts commit 4f397d6ea8bbdf6e808f9dc9db5ecbae291d8cd4.

* Revert "ci: add neovim 0.9.4"

This reverts commit 46fd1b368d27a1892b55381691723db3b30a7527.

* ci: action downloads and installs luals

* ci: remove workspaces from luals

* ci: consistent script naming

* ci: add quality to contributing

* ci: consistent script naming

* ci: add lsp to diagnostics

* ci: temporary find to enumerate home

* ci: add VIMRUNTIME for lls

* ci: temporary find to enumerate home

* ci: temporary find to enumerate home

* ci: remove temporary find to enumerate home

* ci: correct VIMRUNTIME

* ci: add ${3rd}/luv/library

* ci: note VIMRUNTIME override

* ci: add Makefile

* ci: add Makefile

* ci: add Makefile

* ci: add Makefile

* ci: document checks and fixes

* ci: add help check

* ci: add help check

* ci: dummy help failure

* Revert "ci: dummy help failure"

This reverts commit c50cceaa4a.

* ci: document checks and fixes

* ci: document checks and fixes

* ci: matrix nvim version

* ci: matrix nvim version

* Revert "ci: matrix nvim version"

This reverts commit fcef6a11e9.

* Revert "ci: matrix nvim version"

This reverts commit a8cb50d39d.

* ci: matrix nvim version from env

* ci: matrix nvim version from env

* ci: matrix nvim version from env

* ci: matrix nvim version

* ci: matrix nvim version

* ci: matrix per job

* ci: matrix per job

* ci: many lua versions

* ci: move doc to style

* ci: tidy ci and contributing

.github/workflows/ci.yml

@@ -14,22 +14,31 @@ permissions:
 jobs:
   lint:
     runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        lua_version: [ 5.1 ]
+
     steps:
       - uses: actions/checkout@v4
 
       - uses: leafo/gh-actions-lua@v10
         with:
-          luaVersion: "5.1"
+          luaVersion: ${{ matrix.lua_version }}
 
       - uses: leafo/gh-actions-luarocks@v4
 
-      - name: luacheck
-        run: |
-          luarocks install luacheck 1.1.1
-          luacheck lua
+      - run: luarocks install luacheck 1.1.1
+
+      - run: make lint
 
   style:
     runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        stylua_version: [ 0.19.1 ]
+
     steps:
       - uses: actions/checkout@v4
 
@@ -37,8 +46,33 @@ jobs:
         uses: JohnnyMorganz/stylua-action@v3
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          version: "0.19"
+          version: ${{ matrix.stylua_version }}
           args: --check lua
 
-      - name: doc-comments
-        run: ./scripts/doc-comments.sh
+      - run: make style-doc
+
+  check:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        nvim_version: [ v0.9.4 ]
+        luals_version: [ 3.7.3 ]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: ${{ matrix.nvim_version }}
+
+      - name: install luals
+        run: |
+          mkdir -p luals
+          curl -L "https://github.com/LuaLS/lua-language-server/releases/download/${{ matrix.luals_version }}/lua-language-server-${{ matrix.luals_version }}-linux-x64.tar.gz" | tar zx --directory luals
+
+      - name: make check
+        run: VIMRUNTIME=/home/runner/nvim-${{ matrix.nvim_version }}/share/nvim/runtime PATH="luals/bin:${PATH}" make check
+
+      - run: make help-check

.gitignore

@@ -0,0 +1,2 @@
+/luals-out/
+/luals/

.hooks/pre-commit.sh

@@ -1,4 +1,3 @@
-#!/usr/bin/env bash
+#!/bin/sh
 
-stylua . --check || exit 1
-luacheck . || exit 1
+make

.luarc.json

@@ -1,7 +1,14 @@
 {
   "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
   "runtime.version" : "Lua 5.1",
+  "workspace": {
+    "library": [
+      "$VIMRUNTIME/lua/vim/lsp",
+      "${3rd}/luv/library"
+    ]
+  },
   "diagnostics": {
+    "libraryFiles": "Disable",
     "globals": [
       "vim"
     ],

CONTRIBUTING.md

@@ -4,31 +4,76 @@ Thank you for contributing.
 
 See [Development](https://github.com/nvim-tree/nvim-tree.lua/wiki/Development) for environment setup, tips and tools.
 
-## Styling and formatting
+# Tools
 
-Code is formatted using luacheck, and linted using stylua.
-You can install these with:
+Following are used during CI and strongly recommended during local development.
 
-```bash
-luarocks install luacheck
-cargo install stylua
+Lint: [luacheck](https://github.com/lunarmodules/luacheck/)
+
+Style: [StyLua](https://github.com/JohnnyMorganz/StyLua)
+
+Language server: [luals](https://luals.github.io)
+
+You can install them via you OS package manager e.g. `pacman`, `brew` or other via other package managers such as `cargo` or `luarocks`
+
+# Quality
+
+The following quality checks are mandatory and are performed during CI. They run on the entire `lua` directory and return 1 on any failure.
+
+You can run them all via `make` or `make all`
+
+You can setup git hooks to run all checks by running `scripts/setup-hooks.sh`
+
+## lint
+
+1. Runs luacheck quietly using `.luacheck` settings
+
+```sh
+make lint
 ```
 
-You can setup the git hooks by running `scripts/setup-hooks.sh`.
+## style
 
-## Adding new actions
+1. Runs stylua using `.stylua.toml` settings
+1. Runs `scripts/doc-comments.sh` to validate annotated documentation
+
+```sh
+make style
+```
+
+You can automatically fix stylua issues via:
+
+```sh
+make style-fix
+```
+
+## check
+
+1. Runs the checks that the LSP lua language server runs inside nvim using `.luarc.json` via `scripts/luals-check.sh`
+
+```sh
+make check
+```
+
+Assumes `$VIMRUNTIME` is `/usr/share/nvim/runtime`. Adjust as necessary e.g.
+
+```sh
+VIMRUNTIME="/my/path/to/runtime" make check
+```
+
+# Adding New Actions
 
 To add a new action, add a file in `actions/name-of-the-action.lua`. You should export a `setup` function if some configuration is needed.
-Once you did, you should run the `scripts/update-help.sh`.
 
-## Documentation
+Once you did, you should run `make help-update`
+
+# Documentation
 
 When adding new options, you should declare the defaults in the main `nvim-tree.lua` file.
-Once you did, you should run the `scripts/update-help.sh`.
 
 Documentation for options should also be added to `nvim-tree-opts` in `doc/nvim-tree-lua.txt`
 
-## Pull Request
+# Pull Request
 
 Please reference any issues in the description e.g. "resolves #1234".
 

Makefile

@@ -0,0 +1,47 @@
+all: lint style check
+
+#
+# mandatory checks
+#
+lint: luacheck
+
+style: stylua style-doc
+
+check: luals
+
+#
+# subtasks
+#
+luacheck:
+	luacheck -q lua
+
+stylua:
+	stylua lua --check
+
+style-doc:
+	scripts/doc-comments.sh
+
+luals:
+	scripts/luals-check.sh
+
+#
+# fixes
+#
+style-fix:
+	stylua lua
+
+#
+# utility
+#
+help-update:
+	scripts/help-update.sh
+
+#
+# CI
+#
+help-check: help-update
+	git diff --exit-code doc/nvim-tree-lua.txt
+
+
+.PHONY: all lint style check luacheck stylua style-doc luals style-fix help-update help-check
+

lua/nvim-tree/diagnostics.lua

@@ -4,9 +4,6 @@ local log = require "nvim-tree.log"
 
 local M = {}
 
----TODO add "$VIMRUNTIME" to "workspace.library" and use the @enum instead of this integer
----@alias lsp.DiagnosticSeverity integer
-
 ---COC severity level strings to LSP severity levels
 ---@enum COC_SEVERITY_LEVELS
 local COC_SEVERITY_LEVELS = {

lua/nvim-tree/git/runner.lua

@@ -2,11 +2,6 @@ local log = require "nvim-tree.log"
 local utils = require "nvim-tree.utils"
 local notify = require "nvim-tree.notify"
 
--- TODO add "${3rd}/luv/library" to "workspace.library"
----@class uv.uv_handle_t: table
----@class uv.uv_stream_t: uv.uv_handle_t
----@class uv.uv_pipe_t: uv.uv_stream_t
-
 ---@class Runner
 local Runner = {}
 Runner.__index = Runner

lua/nvim-tree/node.lua

@@ -1,9 +1,5 @@
 ---@meta
 
--- TODO add "${3rd}/luv/library" to "workspace.library"
----@class uv.uv_req_t: table
----@class uv.uv_fs_t: uv.uv_req_t
-
 ---@class ParentNode
 ---@field name string
 

scripts/help-update.sh

@@ -2,7 +2,7 @@
 
 # run after changing nvim-tree.lua DEFAULT_OPTS or keymap.lua M.default_on_attach
 # scrapes and updates nvim-tree-lua.txt
-# run from repository root: scripts/update-help.sh
+# run from repository root: scripts/help-update.sh  OR  make help-update
 
 
 #
@@ -38,7 +38,7 @@ sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.lua
 # help human
 echo > /tmp/DEFAULT_ON_ATTACH.help
 sed -E "s/^ *vim.keymap.set\('n', '(.*)',.*api(.*),.*opts\('(.*)'.*$/'\`\1\`' '\3' '|nvim-tree-api\2()|'/g
-" /tmp/DEFAULT_ON_ATTACH.lua | while read line
+" /tmp/DEFAULT_ON_ATTACH.lua | while read -r line
 do
 	eval "printf '%-17.17s %-26.26s %s\n' ${line}" >> /tmp/DEFAULT_ON_ATTACH.help
 done

scripts/luals-check.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+
+# Performs a lua-language-server check on all files.
+# luals-out/check.json will be produced on any issues, returning 1.
+# Outputs only check.json to stdout, all other messages to stderr, to allow jq etc.
+# $VIMRUNTIME specifies neovim runtime path, defaults to "/usr/share/nvim/runtime" if unset.
+
+if [ -z "${VIMRUNTIME}" ]; then
+	export VIMRUNTIME="/usr/share/nvim/runtime"
+fi
+
+DIR_SRC="lua"
+DIR_OUT="luals-out"
+
+# clear output
+rm -rf "${DIR_OUT}"
+mkdir "${DIR_OUT}"
+
+# execute inside lua to prevent luals itself from being checked
+OUT=$(lua-language-server --check="${DIR_SRC}" --configpath="${PWD}/.luarc.json" --checklevel=Information --logpath="${DIR_OUT}" --loglevel=error)
+RC=$?
+
+echo "${OUT}" >&2
+
+if [ $RC -ne 0 ]; then
+	echo "failed with RC=$RC"
+	exit $RC
+fi
+
+# any output is a fail
+case "${OUT}" in
+	*Diagnosis\ complete*)
+		if [ -f "${DIR_OUT}/check.json" ]; then
+			cat "${DIR_OUT}/check.json"
+			exit 1
+		else
+			exit 0
+		fi
+		;;
+	*)
+		exit 1
+		;;
+esac
+