feat: discovery-first tool resolution (make Mason optional)

lua/core/settings.lua

@@ -84,23 +84,15 @@ settings["external_browser"] = "chrome-cli open"
 ---@type boolean
 settings["lsp_inlayhints"] = false
 
--- LSPs installed outside Mason (e.g. via system package manager).
--- These will be configured but not installed by Mason.
--- Key: lspconfig server name, Value: executable name to check availability.
----@type table<string, string>
-settings["external_lsp_deps"] = {
-	nixd = "nixd",
-	nil_ls = "nil",
-	shuck = "shuck", -- shell linter/formatter/LSP (Rust); installed via mise, not Mason
-	-- dartls = "dart",
-}
-
--- LSPs to install during bootstrap.
+-- Language servers to enable, resolved discovery-first at runtime: binary on $PATH is
+-- used as-is; else Mason installs it when it ships a package; else an aggregated warning
+-- asks you to provision it. See `modules.utils.tools` and `completion/mason-lspconfig.lua`.
 -- Full list: https://github.com/neovim/nvim-lspconfig/tree/master/lsp
 ---@type string[]
 settings["lsp_deps"] = {
 	"bashls",
 	"clangd",
+	-- "dartls", -- Dart LSP (ships with the Dart SDK)
 	"dockerls",
 	"gh_actions_ls",
 	-- "gitlab_ci_ls",
@@ -111,7 +103,10 @@ settings["lsp_deps"] = {
 	"lua_ls",
 	"marksman",
 	"neocmake",
+	"nil_ls", -- Nix LSP; prefer the $PATH binary (Nix), else Mason installs it (package `nil`)
+	"nixd", -- Nix LSP (Rust); no Mason package, comes from Nix ($PATH)
 	"ruff",
+	"shuck", -- shell linter/formatter/LSP (Rust); no Mason package, installed via mise
 	"systemd_lsp",
 	"terraformls",
 	"tflint",
@@ -120,39 +115,55 @@ settings["lsp_deps"] = {
 	"zuban",
 }
 
--- Formatters to install during bootstrap (Mason package names).
--- These are managed by Mason and used by conform.nvim.
+-- Formatters to resolve when conform.nvim lazy-loads (first BufWritePre /
+-- :Format). conform formatter names, resolved discovery-first like lsp_deps.
 ---@type string[]
 settings["formatter_deps"] = {
 	"beautysh",
 	"clang-format",
-	"cmakelang",
+	"cmake_format",
 	"fixjson",
 	"gofumpt",
 	"goimports",
 	"mdsf",
+	"nixfmt", -- Nix formatter; prefer the $PATH binary (Nix)
 	"prettier",
 	"superhtml",
 	"shellharden",
+	"statix", -- Nix linter, its `fix` mode doubles as a conform formatter; from Nix ($PATH)
 	"stylua",
 }
 
--- Linters to install during bootstrap (Mason package names).
--- These are managed by Mason and used by nvim-lint.
+-- Linters to resolve discovery-first (nvim-lint linter names). A name mapped
+-- to a filetype resolves on that filetype's FIRST matching event after
+-- nvim-lint lazy-loads (the resolve-only FileType autocmd or a lint event) —
+-- nothing is installed or warned about before such a buffer opens; unmapped
+-- names (typos, manual-only linters) get an immediate deferred pass instead.
 ---@type string[]
 settings["linter_deps"] = {
 	"actionlint",
+	"deadnix", -- Nix dead-code linter; prefer the $PATH binary (Nix)
 	"hadolint",
 	"markdownlint-cli2",
 	"oxlint",
 	-- "rumdl", -- markdownlint Rust rewrite; waiting for rule coverage to mature
-	"golangci-lint",
+	"golangcilint",
 	"selene",
 	"shellcheck",
+	"shuck", -- shell linter for yaml.github `run:` blocks; no Mason package, installed via mise
+	"statix", -- Nix linter; prefer the $PATH binary (Nix)
 	"systemdlint",
+	"zsh", -- `zsh -n` syntax check via the system shell itself
 }
 
--- Debug Adapter Protocol (DAP) clients to install and configure during bootstrap.
+-- Deadline (ms) for background Mason work before the aggregated missing-tool warning
+-- flushes anyway. Gates each tracked install (its own window) AND the registry refresh
+-- wait; late completions still recover. Non-positive values use the default.
+---@type number
+settings["tool_install_timeout"] = 300000
+
+-- DAP adapters to enable (mason-nvim-dap adapter names), resolved
+-- discovery-first when nvim-dap lazy-loads (first :Dap* command).
 -- Supported DAPs: https://github.com/jay-babu/mason-nvim-dap.nvim/blob/main/lua/mason-nvim-dap/mappings/source.lua
 ---@type string[]
 settings["dap_deps"] = {
@@ -242,4 +253,35 @@ settings["dashboard_image"] = {
 	[[⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠿⠿⢿⠿⠷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀]],
 }
 
-return require("modules.utils").extend_config(settings, "user.settings")
+local merged = require("modules.utils").extend_config(settings, "user.settings")
+
+-- Migration guard: the discovery-first refactor removed this key; a stale
+-- user/settings.lua would merge it in and feed nothing — its servers would
+-- vanish without a word. (Scheduled: the notifier plugin isn't loaded this
+-- early; the default notify still lands in :messages.)
+if merged.external_lsp_deps ~= nil then
+	-- The removed setting was a MAP of server name -> executable name: tell
+	-- the user to move the KEYS and list them (moving a value like "nil"
+	-- instead of the key "nil_ls" would land an invalid lsp_deps entry).
+	local keys = {}
+	if type(merged.external_lsp_deps) == "table" then
+		for server in pairs(merged.external_lsp_deps) do
+			keys[#keys + 1] = tostring(server)
+		end
+		table.sort(keys)
+	end
+	local names = #keys > 0 and (" (" .. table.concat(keys, ", ") .. ")") or ""
+	vim.schedule(function()
+		vim.notify(
+			"`external_lsp_deps` was removed: non-Mason servers are now discovered\n"
+				.. "from $PATH. Move its KEYS"
+				.. names
+				.. " — the server names, not the\n"
+				.. "executable values — into `lsp_deps` in user/settings.lua.",
+			vim.log.levels.WARN,
+			{ title = "core.settings" }
+		)
+	end)
+end
+
+return merged

lua/modules/configs/completion/conform.lua

@@ -40,6 +40,19 @@ return function()
 		return false
 	end
 
+	---The gates a buffer must pass before an automatic format, grouped into one
+	---named predicate for the format_on_save callback's readability. The
+	---format_on_save SETTING is not re-checked here: its gate lives at the
+	---single place the callback is installed (format_on_save = enabled and …).
+	---@param bufnr integer
+	---@return boolean
+	local function autoformat_allowed(bufnr)
+		return block_list[vim.bo[bufnr].filetype] ~= true
+			and not is_disabled_workspace(bufnr)
+			and not vim.g.disable_autoformat
+			and not vim.b[bufnr].disable_autoformat
+	end
+
 	---Format only git-modified lines using gitsigns hunks + conform range format
 	---@param bufnr integer
 	---@return boolean @true if modifications were formatted
@@ -87,6 +100,8 @@ return function()
 		return true
 	end
 
+	local tools = require("modules.utils.tools")
+
 	require("modules.utils").load_plugin("conform", {
 		default_format_opts = {
 			timeout_ms = format_timeout,
@@ -132,27 +147,18 @@ return function()
 				args = { "fix", "--stdin" },
 				stdin = true,
 			},
-			-- prettier: stdin mode does not work under bun's node shim,
-			-- so use --write (file-based) mode instead.
+			-- prettier: stdin is broken under bun's node shim, so use --write on
+			-- conform's temp copy (`stdin = false` points $FILENAME at a
+			-- `.conform.$RANDOM.*` copy; the real file is never touched).
 			prettier = {
 				command = "prettier",
 				args = { "--write", "$FILENAME" },
 				stdin = false,
 			},
 		},
 		format_on_save = format_on_save_enabled and function(bufnr)
-			-- Check disabled filetypes
-			if block_list[vim.bo[bufnr].filetype] == true then
-				return
-			end
-
-			-- Check disabled workspaces
-			if is_disabled_workspace(bufnr) then
-				return
-			end
-
-			-- Check global toggle
-			if vim.g.disable_autoformat or vim.b[bufnr].disable_autoformat then
+			-- Disabled filetypes, disabled workspaces, and the global/buffer toggles
+			if not autoformat_allowed(bufnr) then
 				return
 			end
 
@@ -168,6 +174,51 @@ return function()
 		end or false,
 	})
 
+	-- Resolve `formatter_deps` (conform formatter names) discovery-first against
+	-- conform's own registry, so a missing formatter is installed / reported.
+	-- The probe only drives install/warn — nothing on the save path reads it —
+	-- so `defer` moves the resolve off the BufWritePre tick that lazy-loaded
+	-- conform; the resolver itself keeps the same-tick guarantee that Mason's
+	-- bin dir is on $PATH before the replayed save's spawns.
+	tools.resolve_runtime_tools("conform.nvim", settings.formatter_deps, function(name)
+		-- get_formatter_config is conform's @private API; if dropped, degrade to
+		-- "resolves itself" rather than misreporting every formatter as unknown.
+		local conform = require("conform")
+		if type(conform.get_formatter_config) ~= "function" then
+			return { binary = nil }
+		end
+		-- get_formatter_config runs a function-form override directly, so pcall keeps a
+		-- throwing override (a broken config) from being misread as an unknown name.
+		local ok, config, err = pcall(conform.get_formatter_config, name)
+		if not ok then
+			return { broken = tostring(config) }
+		end
+		if config then
+			-- A function-form command resolves per buffer at format time (e.g. the
+			-- builtin from_node_modules): treat it as self-resolving rather than
+			-- evaluating it for a representative binary — a node_modules command
+			-- shouldn't map to a Mason install anyway.
+			if type(config.command) == "function" then
+				return { binary = nil }
+			end
+			return { binary = config.command }
+		end
+		-- (nil, err) is a real formatter with a broken config; bare nil is an unknown name.
+		if type(err) == "string" then
+			return { broken = err }
+		end
+		-- A function-form override may legitimately return nil for the
+		-- probe-time buffer (this probe runs on a scheduled tick against
+		-- whatever buffer happens to be current): its existence proves the
+		-- name real, but nothing is verifiable — report it unresolved
+		-- (missing bucket, tailored reason) instead of a typo or a silent pass.
+		local overrides = conform.formatters
+		if type(overrides) == "table" and type(overrides[name]) == "function" then
+			return { unresolved = true }
+		end
+		return nil
+	end, nil, { defer = true })
+
 	-- User commands
 	vim.api.nvim_create_user_command("Format", function(args)
 		local range = nil

lua/modules/configs/completion/lsp.lua

@@ -1,30 +1,18 @@
 return function()
+	-- Handler/probe machinery first (no discovery yet): sets up the read
+	-- trigger the override pass below relies on.
 	require("completion.mason-lspconfig").setup()
 
-	local opts = {
-		capabilities = require("modules.utils").get_lsp_capabilities(),
-	}
-	-- Configure LSPs that are not managed by Mason but are available in `nvim-lspconfig`.
-	-- Servers are defined in `settings.external_lsp_deps` as { server_name = "executable" }.
-	for lsp_name, exe in pairs(require("core.settings").external_lsp_deps) do
-		if vim.fn.executable(exe) == 1 then
-			local ok, _opts = pcall(require, "user.configs.lsp-servers." .. lsp_name)
-			if not ok then
-				local default_ok, default_opts = pcall(require, "completion.servers." .. lsp_name)
-				if default_ok then
-					_opts = default_opts
-				end
-			end
-			if type(_opts) == "table" then
-				local final_opts = vim.tbl_deep_extend("keep", _opts, opts)
-				require("modules.utils").register_server(lsp_name, final_opts)
-			else
-				require("modules.utils").register_server(lsp_name, opts)
-			end
-		end
-	end
+	-- Run `user.configs.lsp` with its vim.lsp.config registrations recorded: a
+	-- mid-session install registers after this point, and the replay keeps the
+	-- user's overrides on top regardless of timing.
+	-- `user.configs.lsp-servers.<name>` remains the richer per-server hook.
+	require("completion.mason-lspconfig").run_user_lsp_overrides()
 
-	pcall(require, "user.configs.lsp")
+	-- Discovery LAST (Mason-installed / on $PATH / installable / missing,
+	-- driven by `settings.lsp_deps`): user runtime registrations above must be
+	-- visible to the unknown/binary classification.
+	require("completion.mason-lspconfig").resolve_deps()
 
 	-- Start LSPs
 	pcall(vim.cmd.LspStart)