chore: modernize .luarc.json to nested format and add busted library #267

New issue

Closed

opened 2026-02-27 00:22:11 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-02-27 00:22:11 +00:00

Problem

The current .luarc.json uses the flat key format ("runtime.version", "workspace.library" as top-level dotted strings) rather than the standard nested object format used by the Neovim project's own .luarc.json and the LuaLS schema. Both formats work, but the nested format is what LuaLS tooling and the official JSON schema expect, and what most Neovim plugin boilerplates ship.

Additionally, tests/ uses busted (declared in cp.nvim-scm-1.rockspec as a test dependency), but the busted library path is not included in .luarc.json, meaning LuaLS reports unknown globals (describe, it, before_each, etc.) in test files. These are currently handled via vim.yaml (selene config) but not in the LuaLS workspace.

Proposed solution

Migrate to nested format and add the busted LuaLS library:

{
  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
  "runtime": {
    "version": "LuaJIT",
    "path": ["lua/?.lua", "lua/?/init.lua"]
  },
  "workspace": {
    "library": ["$VIMRUNTIME/lua", "${3rd}/luv/library", "${3rd}/busted/library"],
    "checkThirdParty": false
  },
  "diagnostics": {
    "globals": ["vim"]
  },
  "completion": {
    "callSnippet": "Replace"
  }
}

The ${3rd}/busted/library path provides LuaLS types for describe, it, before_each, spy, stub etc. — matching what the selene vim.yaml already declares as globals.

Alternatives considered

Keeping the flat format. It works identically at runtime, but the nested format is the documented standard and reduces confusion for contributors familiar with the LuaLS schema.

## Problem The current `.luarc.json` uses the flat key format (`"runtime.version"`, `"workspace.library"` as top-level dotted strings) rather than the standard nested object format used by the Neovim project's own `.luarc.json` and the LuaLS schema. Both formats work, but the nested format is what LuaLS tooling and the official JSON schema expect, and what most Neovim plugin boilerplates ship. Additionally, `tests/` uses busted (declared in `cp.nvim-scm-1.rockspec` as a test dependency), but the busted library path is not included in `.luarc.json`, meaning LuaLS reports unknown globals (`describe`, `it`, `before_each`, etc.) in test files. These are currently handled via `vim.yaml` (selene config) but not in the LuaLS workspace. ## Proposed solution Migrate to nested format and add the busted LuaLS library: ```json { "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json", "runtime": { "version": "LuaJIT", "path": ["lua/?.lua", "lua/?/init.lua"] }, "workspace": { "library": ["$VIMRUNTIME/lua", "${3rd}/luv/library", "${3rd}/busted/library"], "checkThirdParty": false }, "diagnostics": { "globals": ["vim"] }, "completion": { "callSnippet": "Replace" } } ``` The `${3rd}/busted/library` path provides LuaLS types for `describe`, `it`, `before_each`, `spy`, `stub` etc. — matching what the selene `vim.yaml` already declares as globals. ## Alternatives considered Keeping the flat format. It works identically at runtime, but the nested format is the documented standard and reduces confusion for contributors familiar with the LuaLS schema.