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

lua/core/settings.lua

@@ -57,7 +57,8 @@ settings["disabled_plugins"] = {}
 -- These settings will override the defaults during initialization.
 -- Parameters will auto-complete as you type.
 -- Example: { sky = "#04A5E5" }
----@type palette[]
+---@type palette
+---@diagnostic disable-next-line: missing-fields
 settings["palette_overwrite"] = {}
 
 -- Set the colorscheme here.
@@ -84,23 +85,19 @@ 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. Names whose filetypes lspconfig knows resolve on that
+-- filetype's FIRST buffer (a late sweep classifies the rest once per session); names
+-- with user overrides, repo modules that override filetypes, or no filetype data
+-- resolve on the first file open. 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 +108,10 @@ settings["lsp_deps"] = {
 	"lua_ls",
 	"marksman",
 	"neocmake",
+	"nil_ls", -- Nix LSP; the Nix-provisioned $PATH binary is preferred
+	"nixd", -- Nix LSP (Rust); provisioned from Nix ($PATH)
 	"ruff",
+	"shuck", -- shell linter/formatter/LSP (Rust); installed via mise by choice ($PATH wins)
 	"systemd_lsp",
 	"terraformls",
 	"tflint",
@@ -120,39 +120,56 @@ 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; installed via mise by choice
+	"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. Missing or non-positive values fall back to
+-- the resolver's DEFAULT_TOOL_INSTALL_TIMEOUT_MS in `modules/utils/tools.lua`.
+---@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 or debug keymap).
 -- 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 +259,58 @@ 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.
+if merged.external_lsp_deps ~= nil then
+	-- The removed setting was a MAP of server name -> executable name, but a
+	-- stale override can survive in any shape: classify before advising so the
+	-- guidance never presents numeric indices as keys, never drops entries a
+	-- half-migrated LIST residue still carries, and always names the final
+	-- step (deleting the dead key). Neither group suppresses the other.
+	local string_keys, list_items = {}, {}
+	if type(merged.external_lsp_deps) == "table" then
+		for k, v in pairs(merged.external_lsp_deps) do
+			if type(k) == "string" then
+				string_keys[#string_keys + 1] = k
+			elseif type(k) == "number" and type(v) == "string" then
+				list_items[#list_items + 1] = v
+			end
+		end
+		table.sort(string_keys)
+		table.sort(list_items)
+	end
+	local guidance
+	if #string_keys > 0 and #list_items > 0 then
+		guidance = "Move its KEYS ("
+			.. table.concat(string_keys, ", ")
+			.. ") AND its list entries ("
+			.. table.concat(list_items, ", ")
+			.. ")\n— all of them server names — into `lsp_deps`, then delete `external_lsp_deps`."
+	elseif #string_keys > 0 then
+		guidance = "Move its KEYS ("
+			.. table.concat(string_keys, ", ")
+			.. ") — the server names, not the\n"
+			.. "executable values — into `lsp_deps`, then delete `external_lsp_deps`."
+	elseif #list_items > 0 then
+		guidance = "It now holds a LIST ("
+			.. table.concat(list_items, ", ")
+			.. ") — those are already the\n"
+			.. "server names; move them into `lsp_deps` and delete `external_lsp_deps`."
+	else
+		guidance = "It is empty or not a map — delete `external_lsp_deps` from user/settings.lua."
+	end
+	-- (Scheduled: the notifier plugin isn't loaded this early; the default
+	-- notify still lands in :messages.)
+	vim.schedule(function()
+		vim.notify(
+			"`external_lsp_deps` was removed: non-Mason servers are now discovered\nfrom $PATH. " .. guidance,
+			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,31 +147,22 @@ 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: the --write-on-temp-copy shape dates from the bun
+			-- node-shim era (stdin was broken); mise ships real node now, so
+			-- stdin likely works again — kept pending re-evaluation. `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
+			if not autoformat_allowed(bufnr) then
 				return
 			end
 
-			-- Format only modified lines if enabled
 			if format_modifications_only then
 				if format_modifications(bufnr) then
 					return
@@ -168,6 +174,58 @@ 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 it vanishes, every
+		-- formatter is UNVERIFIABLE — report unresolved with the reason (missing
+		-- bucket, immediate flush) instead of silently classifying them all as
+		-- self-resolving, which would turn off installs and warnings wholesale.
+		local conform = require("conform")
+		if type(conform.get_formatter_config) ~= "function" then
+			return {
+				unresolved = true,
+				reason = "conform.get_formatter_config is unavailable (conform API drift?) — formatters cannot be verified",
+			}
+		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
+			-- The reason rides on the probe result: the phrasing is conform's,
+			-- not the shared resolver's (nvim-lint shares resolve_runtime_tools).
+			return { unresolved = true, reason = "config resolves per buffer and could not be verified at startup" }
+		end
+		return nil
+	end, nil, { defer = true })
+
 	-- User commands
 	vim.api.nvim_create_user_command("Format", function(args)
 		local range = nil
@@ -226,7 +284,7 @@ return function()
 		end
 	end, { nargs = 1, complete = "filetype" })
 
-	-- Auto stop shell LSPs for .env files (migrated from null-ls config).
+	-- Auto stop shell LSPs for .env files.
 	-- Both bashls and shuck attach to .env's `sh` filetype and only add noise there.
 	vim.api.nvim_create_autocmd("LspAttach", {
 		callback = function(event)

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)