init

Author: sindrip

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: nightly
+      - run: make test
+
+  style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JohnnyMorganz/stylua-action@v4
+        with:
+          token: ${{ github.token }}
+          version: latest
+          args: --check .

.luarc.json

@@ -0,0 +1,12 @@
+{
+  "runtime": {
+    "version": "LuaJIT"
+  },
+  "workspace": {
+    "library": [
+      "$VIMRUNTIME",
+      "${3rd}/luv/library"
+    ],
+    "checkThirdParty": false
+  }
+}

.styluaignore

@@ -0,0 +1 @@
+test/fixtures/

Makefile

@@ -0,0 +1,11 @@
+test:
+	nvim --headless -l test/resolve_test.lua
+	nvim --headless -l test/compute_edits_test.lua
+	nvim --headless -l test/format_test.lua
+	nvim --headless -l test/proxy_test.lua
+	nvim --headless -l test/pipeline_test.lua
+
+style:
+	stylua --check .
+
+.PHONY: test style

README.md

@@ -0,0 +1,103 @@
+# formatls.nvim
+
+An in-process LSP formatting server for Neovim. Runs as a native LSP client — no external binary needed.
+
+Supports CLI formatters (biome, prettier, stylua), LSP code actions (organize imports), and chaining multiple steps in a pipeline. Automatically resolves local `node_modules/.bin` binaries and detects config files.
+
+Requires Neovim 0.12+.
+
+## Install
+
+With vim.pack:
+
+```lua
+vim.pack.add("https://github.com/sindrip/formatls.nvim")
+```
+
+With lazy.nvim:
+
+```lua
+{ "sindrip/formatls.nvim" }
+```
+
+## Setup
+
+```lua
+vim.lsp.config.formatls = {
+  init_options = {
+    formatters_by_ft = {
+      typescript = {
+        { "biome" },                                      -- try biome first
+        { "source.organizeImports", "prettier" },         -- fall back to organize imports + prettier
+      },
+      go = {
+        { "source.organizeImports", "source.format" },   -- code actions via gopls
+      },
+      lua = {
+        { "stylua" },
+      },
+    },
+  },
+}
+
+vim.lsp.enable("formatls")
+```
+
+Then format with `vim.lsp.buf.format()` or your preferred keymap.
+
+## How it works
+
+formatls registers as an LSP server that advertises `documentFormattingProvider`. It proxies formatting capabilities from other LSP servers on the buffer so that all format requests go through formatls.
+
+### `formatters_by_ft`
+
+Each filetype maps to a list of **groups**. Groups are tried in order — the first group where all CLI formatters are available is used.
+
+A group is a list of steps, executed sequentially:
+
+| Step | Description |
+|---|---|
+| `"biome"`, `"prettier"`, `"stylua"` | CLI formatter — must have a spec in `lua/formatls/formatters/` |
+| `"source.organizeImports"` | LSP code action — sent to servers that support `textDocument/codeAction` |
+| `"source.format"` | LSP formatting — delegated to the original server's formatter |
+
+### CLI formatter resolution
+
+For each CLI formatter, formatls:
+
+1. Looks up the formatter spec by name (e.g. `require("formatls.formatters.biome")`)
+2. Searches for a local binary in `node_modules/.bin/` (walking up the directory tree)
+3. Falls back to a global binary on `$PATH`
+4. Checks for required config files (e.g. `biome.json` for biome)
+
+If any step fails, the group is skipped and the next group is tried.
+
+### Fallback
+
+When no groups are configured for a filetype (or none are viable), formatls delegates directly to the original LSP server's formatter.
+
+## Custom formatters
+
+Define custom formatter specs inline:
+
+```lua
+vim.lsp.config.formatls = {
+  init_options = {
+    formatters = {
+      my_formatter = {
+        cmd = "my-formatter",
+        args = function(path)
+          return { "--stdin-filepath", path }
+        end,
+        -- optional: required config files (skip if none found)
+        config_files = { ".my-formatter.json" },
+      },
+    },
+    formatters_by_ft = {
+      python = {
+        { "my_formatter" },
+      },
+    },
+  },
+}
+```

lsp/formatls.lua

@@ -0,0 +1,160 @@
+local Server = require("formatls.server")
+local Proxy = require("formatls.proxy")
+local pipeline = require("formatls.pipeline")
+
+local function exec_action(bufnr, action_kind)
+  local params = {
+    textDocument = { uri = vim.uri_from_bufnr(bufnr) },
+    range = {
+      start = { line = 0, character = 0 },
+      ["end"] = { line = vim.api.nvim_buf_line_count(bufnr), character = 0 },
+    },
+    context = { only = { action_kind }, diagnostics = {} },
+  }
+
+  local clients = vim.lsp.get_clients({ bufnr = bufnr, method = "textDocument/codeAction" })
+
+  for _, client in ipairs(clients) do
+    local res = client:request_sync("textDocument/codeAction", params, 5000, bufnr)
+    if res and not res.err then
+      for _, action in ipairs(res.result or {}) do
+        if not action.edit then
+          local resolved = client:request_sync("codeAction/resolve", action, 5000, bufnr)
+          if resolved and resolved.result then
+            action = resolved.result
+          end
+        end
+
+        if action.edit then
+          vim.lsp.util.apply_workspace_edit(action.edit, "utf-16")
+        end
+        if action.command then
+          client:request_sync("workspace/executeCommand", action.command, 5000, bufnr)
+        end
+      end
+    end
+  end
+end
+
+local function get_lsp_edits(proxy, bufnr, method, params)
+  for _, entry in ipairs(proxy:get_formatters(bufnr)) do
+    local client = vim.lsp.get_client_by_id(entry.client_id)
+    if client then
+      local result = client:request_sync(method, params, 5000, bufnr)
+      if result and result.result and #result.result > 0 then
+        return result.result
+      end
+    end
+  end
+  return nil
+end
+
+local function handle_format(self, method, params)
+  local bufnr = vim.uri_to_bufnr(params.textDocument.uri)
+  local filepath = vim.uri_to_fname(params.textDocument.uri)
+  local dirname = vim.fn.fnamemodify(filepath, ":h")
+
+  local steps = pipeline.resolve_group(self.formatters_by_ft[vim.bo[bufnr].filetype] or {}, dirname)
+
+  local lsp_edits = function()
+    return get_lsp_edits(self.proxy, bufnr, method, params)
+  end
+
+  if not steps then
+    return lsp_edits() or {}
+  end
+
+  local original = table.concat(vim.api.nvim_buf_get_lines(bufnr, 0, -1, false), "\n") .. "\n"
+
+  local final = pipeline.run_pipeline(steps, {
+    filepath = filepath,
+    dirname = dirname,
+    get_lsp_edits = lsp_edits,
+    exec_action = function(action_kind, content)
+      local lines = vim.split(content, "\n", { plain = true })
+      if #lines > 0 and lines[#lines] == "" then
+        table.remove(lines)
+      end
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, lines)
+      exec_action(bufnr, action_kind)
+      return table.concat(vim.api.nvim_buf_get_lines(bufnr, 0, -1, false), "\n") .. "\n"
+    end,
+  }, original)
+
+  if not final then
+    -- Rollback buffer to original on pipeline failure
+    local orig_lines = vim.split(original, "\n", { plain = true })
+    if #orig_lines > 0 and orig_lines[#orig_lines] == "" then
+      table.remove(orig_lines)
+    end
+    vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, orig_lines)
+    return {}
+  end
+
+  -- Compute edits from the buffer's current state (which includes any action changes)
+  local current = table.concat(vim.api.nvim_buf_get_lines(bufnr, 0, -1, false), "\n") .. "\n"
+  if final == current then
+    return {}
+  end
+
+  return pipeline.compute_edits(current, final)
+end
+
+local M = Server.new("formatls")
+
+M.capabilities = {
+  documentFormattingProvider = true,
+  documentRangeFormattingProvider = true,
+  textDocumentSync = { openClose = true },
+}
+
+function M:on_init(params)
+  local opts = params.initializationOptions or {}
+  self.formatters_by_ft = opts.formatters_by_ft or {}
+  self.notified_fts = {}
+  self.proxy = Proxy.start(self.name)
+
+  for name, spec in pairs(opts.formatters or {}) do
+    pipeline.add_spec(name, spec)
+  end
+end
+
+function M:on_shutdown()
+  self.proxy:stop()
+end
+
+M.notifications["textDocument/didOpen"] = function(self, params)
+  local bufnr = vim.uri_to_bufnr(params.textDocument.uri)
+  local ft = vim.bo[bufnr].filetype
+
+  if self.notified_fts[ft] then
+    return
+  end
+  self.notified_fts[ft] = true
+
+  local dirname = vim.fn.fnamemodify(vim.uri_to_fname(params.textDocument.uri), ":h")
+  local steps = pipeline.resolve_group(self.formatters_by_ft[ft] or {}, dirname)
+  if not steps then
+    return
+  end
+
+  local names = {}
+  for _, step in ipairs(steps) do
+    names[#names + 1] = step.action or step.cmd or "lsp"
+  end
+
+  local title = table.concat(names, " | ")
+  self.dispatchers.server_request("window/workDoneProgress/create", { token = self.name }, function() end)
+  self.dispatchers.notification("$/progress", { token = self.name, value = { kind = "begin", title = title } })
+  self.dispatchers.notification("$/progress", { token = self.name, value = { kind = "end" } })
+end
+
+M.requests["textDocument/formatting"] = function(self, params)
+  return handle_format(self, "textDocument/formatting", params)
+end
+
+M.requests["textDocument/rangeFormatting"] = function(self, params)
+  return handle_format(self, "textDocument/rangeFormatting", params)
+end
+
+return M:build()

lua/formatls/formatters/biome.lua

@@ -0,0 +1,23 @@
+return {
+  cmd = "biome",
+  args = function(path)
+    return {
+      "format",
+      "--stdin-file-path",
+      path,
+    }
+  end,
+  range_args = function(path, range_start, range_end)
+    return {
+      "format",
+      "--stdin-file-path",
+      path,
+      "--range",
+      range_start .. "-" .. range_end,
+    }
+  end,
+  config_files = {
+    "biome.json",
+    "biome.jsonc",
+  },
+}

lua/formatls/formatters/prettier.lua

@@ -0,0 +1,32 @@
+return {
+  cmd = "prettier",
+  args = function(path)
+    return {
+      "--stdin-filepath",
+      path,
+    }
+  end,
+  range_args = function(path, range_start, range_end)
+    return {
+      "--stdin-filepath",
+      path,
+      "--range-start",
+      tostring(range_start),
+      "--range-end",
+      tostring(range_end),
+    }
+  end,
+  config_files = {
+    ".prettierrc",
+    ".prettierrc.json",
+    ".prettierrc.yml",
+    ".prettierrc.yaml",
+    ".prettierrc.js",
+    ".prettierrc.cjs",
+    ".prettierrc.mjs",
+    ".prettierrc.toml",
+    "prettier.config.js",
+    "prettier.config.cjs",
+    "prettier.config.mjs",
+  },
+}