Nvim Plugin

---
name: nvim-plugin
description:
  Guide for writing Neovim plugins in Lua following official Neovim conventions
  (https://neovim.io/doc/user/lua-plugin/). Use this skill whenever the user is
  creating, modifying, or reviewing a Neovim plugin — including when they
  mention plugin structure, ftplugin, health checks, keymaps, setup() functions,
  vimdoc, LuaCATS annotations, or lazy loading in the context of Neovim plugin
  development. Also trigger when the user is working in a directory that looks
  like a Neovim plugin (contains plugin/, lua/, ftplugin/ subdirectories).
---

# Writing Neovim Plugins

Reference: https://neovim.io/doc/user/lua-plugin/

## File Structure

A standard Neovim plugin layout:

```
myplugin.nvim/
├── plugin/
│   └── myplugin.lua      ← eagerly loaded at startup (keep minimal)
├── lua/
│   └── myplugin/
│       ├── init.lua      ← main module (required as 'myplugin')
│       ├── config.lua    ← option defaults + validation
│       └── health.lua    ← health checks (:checkhealth)
├── ftplugin/
│   └── rust.lua          ← filetype-specific init (optional)
├── doc/
│   └── myplugin.txt      ← vimdoc (generate with panvimdoc)
└── README.md
```

Neovim auto-discovers files in these paths — no registration needed.

## Lazy Loading

Keep `plugin/myplugin.lua` minimal. Defer `require()` into command/mapping
bodies, not at the top of the file. This preserves startup time.

```lua
-- BAD: eager load
local myplugin = require("myplugin")
vim.api.nvim_create_user_command("MyCommand", function()
  myplugin.run()
end, {})

-- GOOD: deferred load
vim.api.nvim_create_user_command("MyCommand", function()
  require("myplugin").run()
end, {})
```

## Keymapping Patterns

Avoid creating keymaps automatically — it conflicts with user config. Two
preferred approaches:

### `<Plug>` Mappings (recommended for simple actions)

```lua
-- In plugin/myplugin.lua
vim.keymap.set("n", "<Plug>(MyPluginAction)", function()
  require("myplugin").do_action()
end)
```

Users then bind it themselves:

```lua
vim.keymap.set("n", "<leader>a", "<Plug>(MyPluginAction)")
```

### Lua Functions (recommended for extensible actions)

```lua
-- Expose the function; let users decide the mapping
require("myplugin").do_action()  -- callable directly
```

For buffer-local mappings (custom UI, ftplugin), always pass `buffer = bufnr`:

```lua
vim.keymap.set("n", "<Plug>(MyPluginBufferAction)", function()
  require("myplugin").buffer_action()
end, { buffer = bufnr })
```

## Initialization: `setup()` Patterns

### Pattern 1: Separated config + init (preferred)

Plugin works out-of-the-box. `setup()` only overrides defaults — no `require()`
calls, side effects, or expensive work. Initialization happens in `plugin/` or
`ftplugin/` scripts, not inside `setup()`.

```lua
-- lua/myplugin/config.lua
local M = {}

M.defaults = {
  enabled = true,
  timeout = 500,
}

M.options = {}

function M.setup(opts)
  M.options = vim.tbl_deep_extend("force", M.defaults, opts or {})
  M.validate()
end

function M.validate()
  vim.validate({
    enabled = { M.options.enabled, "boolean" },
    timeout = { M.options.timeout, "number" },
  })
end

return M
```

### Pattern 2: Combined `setup()` (use when init is complex/risky)

Requires the user to call `setup()` explicitly — even with defaults. Only choose
this when misconfiguration risk is high.

```lua
-- lua/myplugin/init.lua
local M = {}

function M.setup(opts)
  local config = require("myplugin.config")
  config.setup(opts)
  -- initialization logic here
  M._initialized = true
end

return M
```

## Guard Variables

Prevent re-initialization (e.g. from sourcing the same file twice):

```lua
-- plugin/myplugin.lua
if vim.g.loaded_myplugin then
  return
end
vim.g.loaded_myplugin = true
```

For ftplugin (per-buffer, not per-session):

```lua
-- ftplugin/rust.lua
local bufnr = vim.api.nvim_get_current_buf()
-- no session-level guard needed; ftplugin is intentionally per-buffer
```

**Set `filetype` as late as possible** in custom UI buffers so users can
override buffer-local settings via `FileType` autocmds.

## Health Checks

Create `lua/{plugin}/health.lua`. `:checkhealth {plugin}` auto-discovers it.

```lua
-- lua/myplugin/health.lua
local M = {}

function M.check()
  vim.health.start("myplugin")

  -- Check initialization
  local ok, config = pcall(require, "myplugin.config")
  if not ok then
    vim.health.error("myplugin not loaded")
    return
  end

  -- Check config
  if config.options.timeout < 100 then
    vim.health.warn("timeout < 100ms may cause issues")
  else
    vim.health.ok("configuration looks good")
  end

  -- Check external deps
  if vim.fn.executable("some-tool") == 1 then
    vim.health.ok("some-tool found")
  else
    vim.health.error("some-tool not found in PATH")
  end
end

return M
```

## Type Annotations (LuaCATS)

Annotate public APIs with LuaCATS for lua-language-server (luals):

```lua
---@class MyPlugin.Config
---@field enabled boolean
---@field timeout integer

---@param opts? MyPlugin.Config
function M.setup(opts) end

---@return MyPlugin.Config
function M.get_config() end
```

Integrate `lua-typecheck-action` in CI to catch type errors before users do.

## In-Process LSP Actions (advanced UI pattern)

For plugins with custom UIs, expose actions as LSP code-actions so users can
invoke them via standard `vim.lsp.buf.code_action()`:

```lua
-- Users can then filter and apply specific actions:
vim.lsp.buf.code_action({
  apply = true,
  filter = function(a)
    return a.title == "My Plugin Action"
  end,
})
```

## Versioning & Deprecation

- Follow **SemVer**: `MAJOR.MINOR.PATCH`
- Use `vim.deprecate()` when removing or renaming APIs:

```lua
function M.old_function(opts)
  vim.deprecate("myplugin.old_function", "myplugin.new_function", "2.0.0", "myplugin")
  return M.new_function(opts)
end
```

- Automate releases with `luarocks-tag-release` or `release-please-action`
- Publish to **luarocks** if the plugin has Lua dependencies or is itself a
  dependency

## Documentation (vimdoc)

Provide vimdoc so users can access `:h myplugin` in Neovim.

Generate from Markdown using `panvimdoc`, then regenerate help-tags:

```vim
:helptags doc/
```

## Development Workflow

- Use `:restart` to reload plugin changes during development
- Profile startup impact: `nvim --startuptime /tmp/nvim-startup.log`
- Add `dev = true` to your lazy.nvim spec to load from local path:

```lua
{
  "username/myplugin.nvim",
  dev = true,  -- loads from opts.dev.path/myplugin.nvim
}
```

## Code Style

Follow the project's Lua style (per `.stylua.toml`):

- 2-space indentation
- Double quotes
- 120 char line width
- Sort requires via `stylua`