shepherdjerred/monorepo/lua-helper

Lua Helper

Identify the host before writing Lua. Portable Lua 5.5, Neovim's Lua 5.1 interface, optional LuaJIT extensions, and WezTerm's Lua 5.4 runtime have different APIs and semantics.

Current baselines

Verified 2026-08-03:

Read references/releases.md for the 68-page research ledger. Read references/core-language.md for portable Lua and LuaJIT differences. Read references/neovim.md for current LSP, diagnostics, process, trust, and buffer APIs. Read references/wezterm.md for configuration evaluation, strict mode, events, subprocesses, and mux domains. Read references/tooling-and-security.md for LuaLS, formatters, linters, tests, rocks, and security.

Select the runtime

Before using an API, establish:

1. Lua language/interface version.
2. Whether the runtime is PUC Lua, LuaJIT, or a host embedding.
3. Host application version and stable/nightly channel.
4. Tooling version and project configuration.

In Neovim, target the documented Lua 5.1 interface and check jit before LuaJIT-specific behavior. In WezTerm, target Lua 5.4 and check the API's “Since” version against the installed binary.

Error discipline

Lua APIs commonly return nil, error or status tuples. Check every open, read, write, close, subprocess, and host callback result whose failure matters.

local function read_file(path)
  local file, open_error = io.open(path, "rb")
  if not file then
    return nil, open_error
  end
 
  local content, read_error = file:read("*a")
  local close_ok, close_error = file:close()
  if not content then
    return nil, read_error
  end
  if not close_ok then
    return nil, close_error
  end
  return content
end

Do not bind an unchecked io.open result as a to-be-closed value. Preserve close failures when durability matters.

Tables and sequences

The length operator does not count arbitrary table keys. For a table with holes, #table returns a valid border and is not a reliable element count. Model sequences as contiguous integer keys or count explicitly.

Version-gate table.move, table.unpack, rawlen, __pairs, and related APIs. Lua 5.1 uses global unpack; LuaJIT compatibility libraries can depend on build flags.

Avoid memoization keys built from table.concat({...}): they reject many value types and can collide. Use nested tables keyed by arguments or a deliberately encoded, restricted input domain.

Neovim

Current native LSP setup uses vim.lsp.config and vim.lsp.enable. This replaces nvim-lspconfig's deprecated legacy require('lspconfig').setup framework; nvim-lspconfig itself remains maintained and supplies server definitions.

Use current APIs:

• vim.hl.hl_op() for yank highlighting.
• vim.diagnostic.jump({ count = 1 }) and negative count for navigation.
• vim.api.nvim_set_option_value(name, value, { buf = buffer }) for scoped options.
• vim.system({ program, argument }, { text = true }):wait() for ordinary subprocesses, checking code, signal, and stderr.

Use :trust and vim.secure for project-local configuration. exrc executes project code and is a trust boundary.

WezTerm

Create the configuration with strict mode so invalid options fail:

local wezterm = require("wezterm")
local config = wezterm.config_builder()
config:set_strict_mode(true)
 
return config

WezTerm may evaluate configuration repeatedly. Keep top-level evaluation idempotent and free of side effects such as spawning processes. Config precedence includes CLI and environment overrides before standard paths.

wezterm.run_child_process returns success, stdout, and stderr. Inspect success. Returning false from a wezterm.on callback stops later callbacks and the default action.

Tooling

stylua --check .
luacheck .
selene .
busted

Use the tools configured by the project. Choose Luacheck or Selene deliberately instead of layering both without purpose. Use Busted for behavior-style suites or LuaUnit for lightweight xUnit tests. Use headless Neovim/Plenary only when host integration is part of the contract.

LuaLS supports .luarc.json / .luarc.jsonc, annotations, diagnostics, addons, and stricter type-checking modes. Loading the entire Neovim runtime as a workspace library is valid but broad; prefer an addon or narrow explicit paths when sufficient.

Security

• Load untrusted source only as text with a constrained environment; never accept untrusted binary chunks.
• Avoid shell construction in os.execute and string-form vim.fn.system. Never concatenate untrusted input into a shell command.
• WezTerm and Neovim config execute arbitrary code. Keep secrets out of config and use protected identity/agent mechanisms.
• WezTerm config can execute more than once; repeated evaluation magnifies side effects.
• LuaRocks installation executes rock build/package logic. Inspect sources and rockspecs and pin versions in reproducible environments.
• LuaJIT FFI is an implementation extension with native-memory safety implications; do not assume it exists or is sandboxed.

Review checklist

• Identify portable Lua, LuaJIT, Neovim, or WezTerm before choosing APIs.
• Version-gate language, host, and online-documentation features.
• Check file, process, callback, and cleanup results.
• Do not use # as a general map size or unsafe concatenated memo keys.
• Use current Neovim LSP, highlight, diagnostic, option, and process APIs.
• Make WezTerm config strict, idempotent, and side-effect free at top level.
• Configure LuaLS and one intentional lint/test workflow.
• Treat project config, shells, rocks, binary chunks, and FFI as trust boundaries.
• Preserve the distinction between Neovim's Lua 5.1 interface and optional LuaJIT implementation.