docs: generate server-mapping.md (#13)

4 files changed, 188 insertions, 17 deletions

diff --git a/README.md b/README.md
index b448746..0ec2496 100644
--- a/README.md
+++ b/README.md
@@ -23,12 +23,20 @@
 
 # Introduction
 
-`mason-lspconfig.nvim` registers a setup hook with `lspconfig` that ensures servers installed with `mason.nvim` are set
-up with the necessary extra configuration. It also provides extra convenience commands such as `:LspInstall`. Lastly, it
-also provides convenience APIs that allow you to use mason.nvim as the main control for dynamically setting up installed
-servers on an ad-hoc basis.
+`mason-lspconfig.nvim` closes some gaps that exist between `mason.nvim` and `lspconfig`. Its main responsibilities is
+to:
 
-It is recommended to use this extension if you use `mason.nvim` and `lspconfig`.
+-   register a setup hook with `lspconfig` that ensures servers installed with `mason.nvim` are set up with the necessary
+    configuration
+-   provide extra convenience APIs such as the `:LspInstall` command
+-   allow you to (i) automatically install, and (ii) automatically set up a predefined list of servers
+-   translate between `lspconfig` server names and `mason.nvim` package names (e.g. `sumneko_lua <-> lua-language-server`)
+
+It is recommended to use this extension if you use `mason.nvim` and `lspconfig` (it's strongly recommended for Windows
+users).
+
+**Note: this plugin uses the `lspconfig` server names in the APIs it exposes - not `mason.nvim` package names. [See this
+table for a complete mapping.](./doc/server-mapping.md)**
 
 # Requirements
 
diff --git a/doc/server-mapping.md b/doc/server-mapping.md
new file mode 100644
index 0000000..278f0e4
--- /dev/null
+++ b/doc/server-mapping.md
@@ -0,0 +1,119 @@
+<!--- THIS FILE IS GENERATED. DO NOT EDIT MANUALLY. -->
+| lspconfig server name | mason.nvim package name |
+| --------------------- | ----------------------- |
+| [angularls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#angularls) | angular-language-server |
+| [ansiblels](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ansiblels) | ansible-language-server |
+| [apex_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#apex_ls) | apex-language-server |
+| [arduino_language_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#arduino_language_server) | arduino-language-server |
+| [asm_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#asm_lsp) | asm-lsp |
+| [astro](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) | astro-language-server |
+| [awk_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#awk_ls) | awk-language-server |
+| [bashls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#bashls) | bash-language-server |
+| [beancount](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#beancount) | beancount-language-server |
+| [bicep](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#bicep) | bicep-lsp |
+| [bsl_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#bsl_ls) | bsl-language-server |
+| [clangd](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#clangd) | clangd |
+| [clarity_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#clarity_lsp) | clarity-lsp |
+| [clojure_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#clojure_lsp) | clojure-lsp |
+| [cmake](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#cmake) | cmake-language-server |
+| [codeqlls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#codeqlls) | codeql |
+| [crystalline](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#crystalline) | crystalline |
+| [csharp_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#csharp_ls) | csharp-language-server |
+| [cssls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#cssls) | css-lsp |
+| [cssmodules_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#cssmodules_ls) | cssmodules-language-server |
+| [cucumber_language_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#cucumber_language_server) | cucumber-language-server |
+| [denols](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#denols) | deno |
+| [dhall_lsp_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#dhall_lsp_server) | dhall-lsp |
+| [diagnosticls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#diagnosticls) | diagnostic-languageserver |
+| [dockerls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#dockerls) | dockerfile-language-server |
+| [dotls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#dotls) | dot-language-server |
+| [efm](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#efm) | efm |
+| [elixirls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#elixirls) | elixir-ls |
+| [elmls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#elmls) | elm-language-server |
+| [ember](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ember) | ember-language-server |
+| [emmet_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#emmet_ls) | emmet-ls |
+| [erlangls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#erlangls) | erlang-ls |
+| [esbonio](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#esbonio) | esbonio |
+| [eslint](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#eslint) | eslint-lsp |
+| [flux_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#flux_lsp) | flux-lsp |
+| [foam_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#foam_ls) | foam-language-server |
+| [fortls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#fortls) | fortls |
+| [fsautocomplete](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#fsautocomplete) | fsautocomplete |
+| [golangci_lint_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#golangci_lint_ls) | golangci-lint-langserver |
+| [gopls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#gopls) | gopls |
+| [grammarly](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#grammarly) | grammarly-languageserver |
+| [graphql](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#graphql) | graphql-language-service-cli |
+| [groovyls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#groovyls) | groovy-language-server |
+| [haxe_language_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#haxe_language_server) | haxe-language-server |
+| [hls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#hls) | haskell-language-server |
+| [hoon_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#hoon_ls) | hoon-language-server |
+| [html](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#html) | html-lsp |
+| [intelephense](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#intelephense) | intelephense |
+| [jdtls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#jdtls) | jdtls |
+| [jedi_language_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#jedi_language_server) | jedi-language-server |
+| [jsonls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#jsonls) | json-lsp |
+| [jsonnet_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#jsonnet_ls) | jsonnet-language-server |
+| [julials](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#julials) | julia-lsp |
+| [kotlin_language_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#kotlin_language_server) | kotlin-language-server |
+| [lelwel_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#lelwel_ls) | lelwel |
+| [lemminx](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#lemminx) | lemminx |
+| [ltex](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ltex) | ltex-ls |
+| [marksman](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#marksman) | marksman |
+| [mm0_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#mm0_ls) | metamath-zero-lsp |
+| [nickel_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#nickel_ls) | nickel-lang-lsp |
+| [nimls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#nimls) | nimlsp |
+| [ocamllsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ocamllsp) | ocaml-lsp |
+| [omnisharp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#omnisharp) | omnisharp |
+| [opencl_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#opencl_ls) | opencl-language-server |
+| [perlnavigator](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#perlnavigator) | perlnavigator |
+| [phpactor](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#phpactor) | phpactor |
+| [powershell_es](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#powershell_es) | powershell-editor-services |
+| [prismals](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#prismals) | prisma-language-server |
+| [prosemd_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#prosemd_lsp) | prosemd-lsp |
+| [psalm](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#psalm) | psalm |
+| [puppet](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#puppet) | puppet-editor-services |
+| [purescriptls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#purescriptls) | purescript-language-server |
+| [pylsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#pylsp) | python-lsp-server |
+| [pyright](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#pyright) | pyright |
+| [quick_lint_js](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#quick_lint_js) | quick-lint-js |
+| [r_language_server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#r_language_server) | r-languageserver |
+| [reason_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#reason_ls) | reason-language-server |
+| [remark_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#remark_ls) | remark-language-server |
+| [rescriptls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#rescriptls) | rescript-lsp |
+| [rnix](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#rnix) | rnix-lsp |
+| [robotframework_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#robotframework_ls) | robotframework-lsp |
+| [rome](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#rome) | rome |
+| [rust_analyzer](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#rust_analyzer) | rust-analyzer |
+| [salt_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#salt_ls) | salt-lsp |
+| [serve_d](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#serve_d) | serve-d |
+| [slint_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#slint_lsp) | slint-lsp |
+| [solang](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#solang) | solang |
+| [solargraph](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#solargraph) | solargraph |
+| [solc](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#solc) | solidity |
+| [sorbet](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sorbet) | sorbet |
+| [sourcery](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sourcery) | sourcery |
+| [sqlls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sqlls) | sqlls |
+| [sqls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sqls) | sqls |
+| [stylelint_lsp](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#stylelint_lsp) | stylelint-lsp |
+| [sumneko_lua](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sumneko_lua) | lua-language-server |
+| [svelte](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#svelte) | svelte-language-server |
+| [svlangserver](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#svlangserver) | svlangserver |
+| [svls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#svls) | svls |
+| [tailwindcss](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#tailwindcss) | tailwindcss-language-server |
+| [taplo](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#taplo) | taplo |
+| [teal_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#teal_ls) | teal-language-server |
+| [terraformls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#terraformls) | terraform-ls |
+| [texlab](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#texlab) | texlab |
+| [tflint](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#tflint) | tflint |
+| [theme_check](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#theme_check) | shopify-theme-check |
+| [tsserver](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#tsserver) | typescript-language-server |
+| [vala_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#vala_ls) | vala-language-server |
+| [verible](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#verible) | verible |
+| [vimls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#vimls) | vim-language-server |
+| [visualforce_ls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#visualforce_ls) | visualforce-language-server |
+| [vls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#vls) | vls |
+| [volar](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#volar) | vue-language-server |
+| [vuels](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#vuels) | vetur-vls |
+| [yamlls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#yamlls) | yaml-language-server |
+| [zk](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#zk) | zk |
+| [zls](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#zls) | zls |
\ No newline at end of file
diff --git a/scripts/lua/mason-scripts/mason-lspconfig/generate.lua b/scripts/lua/mason-scripts/mason-lspconfig/generate.lua
index 66c2ba6..88fdc9d 100644
--- a/scripts/lua/mason-scripts/mason-lspconfig/generate.lua
+++ b/scripts/lua/mason-scripts/mason-lspconfig/generate.lua
@@ -4,6 +4,7 @@ local _ = require "mason-core.functional"
 local lspconfig_server_mapping = require "mason-lspconfig.mappings.server"
 local script_utils = require "mason-scripts.utils"
 
+local DOCS_DIR = path.concat { vim.loop.cwd(), "doc" }
 local MASON_LSPCONFIG_DIR = path.concat { vim.loop.cwd(), "lua", "mason-lspconfig" }
 
 local function get_lspconfig(name)
@@ -33,7 +34,7 @@ local function create_lspconfig_filetype_map()
 end
 
 ---@async
-local function ensure_valid_mapping()
+local function ensure_valid_package_name_translations()
     local server_mappings = require "mason-lspconfig.mappings.server"
     local registry = require "mason-registry"
 
@@ -46,9 +47,37 @@ local function ensure_valid_mapping()
     end
 end
 
+---@async
+local function create_server_mapping_docs()
+    local server_mappings = require "mason-lspconfig.mappings.server"
+
+    local table_body = _.compose(
+        _.map(function(pair)
+            local lspconfig_name, mason_name = assert(pair[1]), assert(pair[2])
+            return string.format(
+                "| [%s](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#%s) | %s |",
+                lspconfig_name,
+                lspconfig_name,
+                mason_name
+            )
+        end),
+        _.sort_by(_.head),
+        _.to_pairs
+    )(server_mappings.lspconfig_to_package)
+
+    local table_header = {
+        "| lspconfig server name | mason.nvim package name |",
+        "| --------------------- | ----------------------- |",
+    }
+
+    local output = _.join("\n", _.concat(table_header, table_body))
+    script_utils.write_file(path.concat { DOCS_DIR, "server-mapping.md" }, output)
+end
+
 a.run_blocking(function()
     a.wait_all {
         create_lspconfig_filetype_map,
-        ensure_valid_mapping,
+        ensure_valid_package_name_translations,
+        create_server_mapping_docs,
     }
 end)
diff --git a/scripts/lua/mason-scripts/utils.lua b/scripts/lua/mason-scripts/utils.lua
index 771d419..49a20df 100644
--- a/scripts/lua/mason-scripts/utils.lua
+++ b/scripts/lua/mason-scripts/utils.lua
@@ -1,21 +1,36 @@
 local fs = require "mason-core.fs"
+local _ = require "mason-core.functional"
 
 local M = {}
 
 ---@async
 ---@param path string
 ---@param contents string
----@param flags string
+---@param flags string?
 function M.write_file(path, contents, flags)
-    fs.async.write_file(
-        path,
-        table.concat({
-            "-- THIS FILE IS GENERATED. DO NOT EDIT MANUALLY.",
-            "-- stylua: ignore start",
-            contents,
-        }, "\n"),
-        flags
-    )
+    local header = _.cond({
+        {
+            _.matches "%.lua$",
+            _.always {
+                "-- THIS FILE IS GENERATED. DO NOT EDIT MANUALLY.",
+                "-- stylua: ignore start",
+            },
+        },
+        {
+            _.matches "%.md$",
+            _.always {
+                "<!--- THIS FILE IS GENERATED. DO NOT EDIT MANUALLY. -->",
+            },
+        },
+        {
+            _.T,
+            _.always {
+                "# THIS FILE IS GENERATED. DO NOT EDIT MANUALLY.",
+            },
+        },
+    }, path)
+
+    fs.async.write_file(path, table.concat(_.concat(header, { contents }), "\n"), flags)
 end
 
 return M