ci: generate annotations for Lua types

.github/workflows/gen-annotations.yml

@@ -0,0 +1,40 @@
+name: gen-annotations
+
+on:
+  push:
+    paths:
+      - lsp/**
+      - scripts/gen_json_schemas.lua
+      - scripts/gen_annotations.lua
+      - .github/workflows/gen-annotations.yml
+  workflow_dispatch:
+
+jobs:
+  gen-annotations:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: nightly
+      - name: Generate JSON schemas
+        run: |
+          nvim  -l scripts/gen_json_schemas.lua
+      - name: Generate annotations
+        run: |
+          nvim  -l scripts/gen_annotations.lua
+      - name: Commit generated files
+        env:
+          COMMIT_MSG: |
+            chore: update generated annotations
+            skip-checks: true
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git add -A lua/lspconfig/types
+          git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push)

.github/workflows/lint.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Run luals
         run: |
           export VIMRUNTIME="$(nvim --headless --cmd 'echo $VIMRUNTIME' +q 2>&1)"
-          ./build/luals/bin/lua-language-server --configpath=$(pwd)/.luarc.json --check=lsp/ --checklevel=Hint
+          ./build/luals/bin/lua-language-server --configpath=$(pwd)/.luarc.json --check=lsp/ --check=lua/lspconfig/types/lsp/ --checklevel=Hint
 
 
   stylua:
@@ -57,7 +57,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - run: pip install codespell
-      - run: codespell --quiet-level=2 --check-hidden --skip=./doc/configs.md,./doc/configs.txt --ignore-words=.codespellignorewords
+      - run: codespell --quiet-level=2 --check-hidden --skip=./doc/configs.md,./doc/configs.txt,./lua/lspconfig/types/lsp --ignore-words=.codespellignorewords
 
   commit:
     runs-on: ubuntu-latest

.gitignore

@@ -1,2 +1,3 @@
 neovim
 doc/tags
+schemas

.styluaignore

@@ -0,0 +1 @@
+lua/lspconfig/types/lsp

README.md

@@ -170,6 +170,36 @@ Most of the time, the reason for failure is present in the logs.
 * `:lsp disable [<config_name>]` (`:LspStop` for Nvim 0.11 or older) Stops the given server. Defaults to stopping all servers active on the current buffer. To force stop use `:LspStop!`
 * `:lsp restart [<client_name>]` (`:LspRestart` for Nvim 0.11 or older) Restarts the given client, and attempts to reattach to all previously attached buffers. Defaults to restarting all active servers.
 
+## LSP Settings Type Annotations
+
+`nvim-lspconfig` generates Lua type definitions for each supported LSP server.
+By manually adding annotations (e.g., `---@type lspconfig.settings.server_name`),
+you enable auto-completion and diagnostics for your server settings.
+
+**Example:**
+
+```lua
+---@type vim.lsp.Config
+local config = {
+  ---@type lspconfig.settings.lua_ls
+  settings = {
+    Lua = {
+      runtime = {
+        version = 'LuaJIT',
+      },
+      workspace = {
+        preloadFileSize = 10000,
+        library = {
+          vim.env.VIMRUNTIME,
+        }
+      },
+    },
+  },
+}
+
+vim.lsp.config('lua_ls', config)
+```
+
 ## Contributions
 
 If a language server is missing from [configs.md](doc/configs.md), contributing

doc/lspconfig.txt

@@ -48,6 +48,9 @@ example to activate the "clangd" config: >lua
     -- Enable filetype-based activation of the config.
     vim.lsp.enable('clangd')
 <
+
+lspconfig provides type annotations for LSP settings, see |lspconfig-settings-types|.
+
                                                           *lspconfig-resolved*
 You can call the "index" form of vim.lsp.config to get the resolved config
 without activating it: >lua
@@ -139,6 +142,34 @@ NEW CONFIGS                                           *lspconfig-new*
 To create a new config, see |lsp-config| (requires Nvim 0.11+).
 To contribute a config to nvim-lspconfig, see ../CONTRIBUTING.md.
 
+==============================================================================
+SETTINGS TYPES                                        lspconfig-settings-types
+
+`nvim-lspconfig` generates Lua type definitions for each supported LSP server.
+By manually adding annotations (e.g., `---@type lspconfig.settings.server_name`),
+you enable auto-completion and diagnostics for your server settings.
+
+Example: >lua
+  ---@type vim.lsp.Config
+  local config = {
+    ---@type lspconfig.settings.lua_ls
+    settings = {
+      Lua = {
+        runtime = {
+          version = 'LuaJIT',
+        },
+        workspace = {
+          library = {
+            vim.env.VIMRUNTIME,
+          }
+        },
+      },
+    },
+  }
+
+  vim.lsp.config('lua_ls', config)
+<
+
 ==============================================================================
 COMPLETION SUPPORT                                        *lspconfig-completion*
 

lsp/basedpyright.lua

@@ -34,6 +34,7 @@ return {
     'Pipfile',
     '.git',
   },
+  ---@type lspconfig.settings.basedpyright
   settings = {
     basedpyright = {
       analysis = {

lsp/bashls.lua

@@ -12,6 +12,7 @@
 ---@type vim.lsp.Config
 return {
   cmd = { 'bash-language-server', 'start' },
+  ---@type lspconfig.settings.bashls
   settings = {
     bashIde = {
       -- Glob pattern for finding and parsing shell script files in the workspace.

lsp/cssls.lua

@@ -26,6 +26,7 @@ return {
   filetypes = { 'css', 'scss', 'less' },
   init_options = { provideFormatter = true }, -- needed to enable formatting capabilities
   root_markers = { 'package.json', '.git' },
+  ---@type lspconfig.settings.cssls
   settings = {
     css = { validate = true },
     scss = { validate = true },

lsp/dartls.lua

@@ -16,6 +16,7 @@ return {
     outline = true,
     flutterOutline = true,
   },
+  ---@type lspconfig.settings.dartls
   settings = {
     dart = {
       completeFunctionCalls = true,

lsp/denols.lua

@@ -124,6 +124,7 @@ return {
       on_dir(project_root or deno_lock_root or deno_root)
     end
   end,
+  ---@type lspconfig.settings.denols
   settings = {
     deno = {
       enable = true,

lsp/eslint.lua

@@ -142,6 +142,7 @@ return {
     on_dir(project_root)
   end,
   -- Refer to https://github.com/Microsoft/vscode-eslint#settings-options for documentation.
+  ---@type lspconfig.settings.eslint
   settings = {
     validate = 'on',
     ---@diagnostic disable-next-line: assign-type-mismatch

lsp/fsautocomplete.lua

@@ -31,6 +31,7 @@ return {
     AutomaticWorkspaceInit = true,
   },
   -- this recommended settings values taken from  https://github.com/ionide/FsAutoComplete?tab=readme-ov-file#settings
+  ---@type lspconfig.settings.fsautocomplete
   settings = {
     FSharp = {
       keywordsAutocomplete = true,

lsp/html.lua

@@ -27,6 +27,7 @@ return {
   cmd = { 'vscode-html-language-server', '--stdio' },
   filetypes = { 'html' },
   root_markers = { 'package.json', '.git' },
+  ---@type lspconfig.settings.html
   settings = {},
   init_options = {
     provideFormatter = true,

lsp/intelephense.lua

@@ -30,6 +30,7 @@ return {
   cmd = { 'intelephense', '--stdio' },
   filetypes = { 'php' },
   root_markers = { '.git', 'composer.json' },
+  ---@type lspconfig.settings.intelephense
   settings = {
     intelephense = {
       telemetry = {

lsp/java_language_server.lua

@@ -11,5 +11,6 @@ return {
   cmd = { 'java-language-server' },
   filetypes = { 'java' },
   root_markers = { 'build.gradle', 'build.gradle.kts', 'pom.xml', '.git' },
+  ---@type lspconfig.settings.java_language_server
   settings = {},
 }

lsp/ltex.lua

@@ -77,6 +77,7 @@ return {
   filetypes = filetypes,
   root_markers = { '.git' },
   get_language_id = get_language_id,
+  ---@type lspconfig.settings.ltex
   settings = {
     ltex = {
       enabled = enabled_ids,

lsp/lua_ls.lua

@@ -85,6 +85,7 @@ return {
   filetypes = { 'lua' },
   root_markers = vim.fn.has('nvim-0.11.3') == 1 and { root_markers1, root_markers2, { '.git' } }
     or vim.list_extend(vim.list_extend(root_markers1, root_markers2), { '.git' }),
+  ---@type lspconfig.settings.lua_ls
   settings = {
     Lua = {
       codeLens = { enable = true },

lsp/omnisharp.lua

@@ -43,6 +43,7 @@ return {
       workspaceFolders = false, -- https://github.com/OmniSharp/omnisharp-roslyn/issues/909
     },
   },
+  ---@type lspconfig.settings.omnisharp
   settings = {
     FormattingOptions = {
       -- Enables support for reading code style, naming convention and analyzer

lsp/perlls.lua

@@ -17,6 +17,7 @@ return {
     '--port 13603',
     '--nostdio 0',
   },
+  ---@type lspconfig.settings.perlls
   settings = {
     perl = {
       perlCmd = 'perl',

lsp/perlpls.lua

@@ -10,6 +10,7 @@
 ---@type vim.lsp.Config
 return {
   cmd = { 'pls' },
+  ---@type lspconfig.settings.perlpls
   settings = {
     perl = {
       perlcritic = { enabled = false },

lsp/pyright.lua

@@ -34,6 +34,7 @@ return {
     'Pipfile',
     '.git',
   },
+  ---@type lspconfig.settings.pyright
   settings = {
     python = {
       analysis = {

lsp/rescriptls.lua

@@ -39,6 +39,7 @@ return {
   cmd = { 'rescript-language-server', '--stdio' },
   filetypes = { 'rescript' },
   root_markers = { 'bsconfig.json', 'rescript.json', '.git' },
+  ---@type lspconfig.settings.rescriptls
   settings = {},
   init_options = {
     extensionConfiguration = {

lsp/ruff_lsp.lua

@@ -26,5 +26,6 @@ return {
   cmd = { 'ruff-lsp' },
   filetypes = { 'python' },
   root_markers = { 'pyproject.toml', 'ruff.toml', '.git' },
+  ---@type lspconfig.settings.ruff_lsp
   settings = {},
 }

lsp/rust_analyzer.lua

@@ -143,6 +143,7 @@ return {
       },
     },
   },
+  ---@type lspconfig.settings.rust_analyzer
   settings = {
     ['rust-analyzer'] = {
       lens = {

lsp/solargraph.lua

@@ -13,6 +13,7 @@
 ---@type vim.lsp.Config
 return {
   cmd = { 'solargraph', 'stdio' },
+  ---@type lspconfig.settings.solargraph
   settings = {
     solargraph = {
       diagnostics = true,

lsp/spectral.lua

@@ -14,6 +14,7 @@ return {
   cmd = { 'spectral-language-server', '--stdio' },
   filetypes = { 'yaml', 'json', 'yml' },
   root_markers = { '.spectral.yaml', '.spectral.yml', '.spectral.json', '.spectral.js' },
+  ---@type lspconfig.settings.spectral
   settings = {
     enable = true,
     run = 'onType',

lsp/stylelint_lsp.lua

@@ -51,5 +51,6 @@ return {
     'wxss',
   },
   root_markers = root_file,
+  ---@type lspconfig.settings.stylelint_lsp
   settings = {},
 }

lsp/svlangserver.lua

@@ -15,6 +15,7 @@ return {
   cmd = { 'svlangserver' },
   filetypes = { 'verilog', 'systemverilog' },
   root_markers = { '.svlangserver', '.git' },
+  ---@type lspconfig.settings.svlangserver
   settings = {
     systemverilog = {
       includeIndexing = { '*.{v,vh,sv,svh}', '**/*.{v,vh,sv,svh}' },

lsp/tailwindcss.lua

@@ -73,6 +73,7 @@ return {
       },
     },
   },
+  ---@type lspconfig.settings.tailwindcss
   settings = {
     tailwindCSS = {
       validate = true,

lsp/yamlls.lua

@@ -64,6 +64,7 @@ return {
   cmd = { 'yaml-language-server', '--stdio' },
   filetypes = { 'yaml', 'yaml.docker-compose', 'yaml.gitlab', 'yaml.helm-values' },
   root_markers = { '.git' },
+  ---@type lspconfig.settings.yamlls
   settings = {
     -- https://github.com/redhat-developer/vscode-redhat-telemetry#how-to-disable-telemetry-reporting
     redhat = { telemetry = { enabled = false } },