diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c88c11c4bd5..bd6cd4e0451 100644
--- a/.github/workflows/ci.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000000..e4d0be68682
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+/luals-out/
+/luals/
diff --git a/.hooks/pre-commit.sh b/.hooks/pre-commit.sh
index a01efc2db2c..5b139ec3263 100755
--- a/.hooks/pre-commit.sh
+++ b/.hooks/pre-commit.sh
@@ -1,4 +1,3 @@
-#!/usr/bin/env bash
+#!/bin/sh
 
-stylua . --check || exit 1
-luacheck . || exit 1
+make
diff --git a/.luarc.json b/.luarc.json
index 6ae9cf62374..8c49d56db19 100644
--- a/.luarc.json
+++ b/.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"
     ],
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ceeec034747..fc5d33fc185 100644
--- a/CONTRIBUTING.md
+++ b/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
+```
+
+## style
+
+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
 ```
 
-You can setup the git hooks by running `scripts/setup-hooks.sh`.
+Assumes `$VIMRUNTIME` is `/usr/share/nvim/runtime`. Adjust as necessary e.g.
 
-## Adding new actions
+```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".
 
diff --git a/Makefile b/Makefile
new file mode 100644
index 00000000000..7260b83a972
--- /dev/null
+++ b/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
+
diff --git a/lua/nvim-tree/diagnostics.lua b/lua/nvim-tree/diagnostics.lua
index 6ca13c9c067..6d0e1354149 100644
--- a/lua/nvim-tree/diagnostics.lua
+++ b/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 = {
diff --git a/lua/nvim-tree/git/runner.lua b/lua/nvim-tree/git/runner.lua
index 8e2635df8bb..7ec4ab6ddca 100644
--- a/lua/nvim-tree/git/runner.lua
+++ b/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
diff --git a/lua/nvim-tree/node.lua b/lua/nvim-tree/node.lua
index 323fc53c4c4..0ea6e76a845 100644
--- a/lua/nvim-tree/node.lua
+++ b/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
 
diff --git a/scripts/update-help.sh b/scripts/help-update.sh
similarity index 92%
rename from scripts/update-help.sh
rename to scripts/help-update.sh
index 522a5a44555..3fa00e907af 100755
--- a/scripts/update-help.sh
+++ b/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
diff --git a/scripts/luals-check.sh b/scripts/luals-check.sh
new file mode 100755
index 00000000000..b86fbc6fdf2
--- /dev/null
+++ b/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
+