# nvim

Personal Neovim config based on `kickstart.nvim`, tuned for backend-heavy work
in JavaScript/TypeScript, C/C++, Kubernetes, and server development.

This README is the working manual for what is configured, why it exists, and
how to use it quickly.

## Design principles

- Additive, not disruptive: new plugins and mappings are added without replacing
  existing behavior.
- Modular plugin specs: each concern lives in `lua/custom/plugins/*.lua`.
- Terminal-friendly workflow: most actions map to short leader sequences and
  preserve CLI-first habits.
- Keep startup stable: major features are lazy-loaded by command, filetype, or
  explicit keymaps where possible.

## Repository layout

- `init.lua`: base options, core plugin setup, LSP, formatting, treesitter.
- `lua/custom/plugins/*.lua`: modular plugin specs and custom behavior.
- `doc/nvim.txt`: Vim help document (`:help nvim-config`).
- `lazy-lock.json`: plugin lockfile managed by lazy.nvim.

## Quick validation commands

Run these after config changes:

```sh
nvim --headless "+qa"
nvim --headless "+checkhealth" "+qa"
luac -p init.lua lua/custom/**/*.lua
```

Useful maintenance commands:

```sh
nvim --headless "+Lazy! sync" "+qa"
nvim --headless "+MasonToolsInstallSync" "+qa"
```

## Keymap manual

### Git workflow

- `<leader>Gg`: open Neogit UI
- `<leader>Gd`: open Diffview
- `<leader>GD`: close Diffview
- `<leader>Gf`: Diffview file history (current file)
- `<leader>GF`: Diffview repo history
- `<leader>h...`: Gitsigns hunk actions (`:which-key <leader>h`)

### Diagnostics and code navigation

- `<leader>gd`: goto definition
- `<leader>gD`: goto declaration
- `<leader>gr`: goto references
- `<leader>gi`: goto implementation
- `<leader>gt`: goto type definition
- `<leader>xx`: Trouble diagnostics
- `<leader>xw`: Trouble workspace diagnostics
- `<leader>xd`: Trouble current buffer diagnostics
- `<leader>xq`: Trouble quickfix list
- `<leader>xl`: Trouble location list
- `<leader>tc`: toggle treesitter context header
- `<leader>jm` / `<leader>jk`: next/previous function start
- `<leader>jM` / `<leader>jK`: next/previous function end
- `<leader>jc` / `<leader>jC`: next/previous class start
- Textobject select (operator-pending/visual): `af`/`if` for function, `ac`/`ic` for class

### Yank references (AI-friendly)

- `<leader>ya`: yank absolute reference with location and symbol
- `<leader>yr`: yank relative reference with location and symbol
- `<leader>yf`: yank current buffer file as `@relative/path`
- `<leader>yd`: yank current buffer parent directory as `@relative/dir`

### Tests and debug

- `<leader>nr`: neotest run nearest
- `<leader>nf`: neotest run current file
- `<leader>ns`: neotest run suite (cwd)
- `<leader>nd`: neotest debug nearest via DAP
- `<leader>nn`: neotest summary toggle
- `<leader>no`: neotest output for nearest test
- `<leader>nO`: neotest output panel toggle
- `<leader>na`: attach to running neotest process
- `<leader>nS`: stop neotest run

Existing DAP keys are unchanged:

- `<F5>` continue/start, `<F1>` step into, `<F2>` step over, `<F3>` step out
- `<F7>` toggle dap-ui, `<leader>b` toggle breakpoint, `<leader>B` conditional bp

### Search, replace, and explorer

- `<leader>sR`: project search/replace with grug-far
- `<leader>eo`: open Oil explorer view (optional, non-default explorer)

### CMake workflow (optional)

- `<leader>cg`: CMake generate
- `<leader>cb`: CMake build
- `<leader>cr`: CMake run
- `<leader>ct`: CMake test
- `<leader>cc`: CMake select build type

## Plugin stack by workflow

### LSP and language intelligence

- `nvim-lspconfig` + `mason-lspconfig` + `mason-tool-installer`
- Vue integration:
  - `vue_ls` enabled
  - `ts_ls` scoped to `vue` with `@vue/typescript-plugin`
  - keeps `typescript-tools.nvim` available for TS/JS workflows
- Kubernetes/Helm integration:
  - `yamlls` with schema mappings for Kubernetes, Helm chart, Helmfile,
    and Kustomize
  - `helm_ls` enabled
  - `vim-helm` added for Helm syntax support

### Treesitter and structural editing

- `nvim-treesitter` uses current API (`require('nvim-treesitter').setup()`).
- `nvim-treesitter-context` provides sticky scope context.
- `nvim-treesitter-textobjects` adds structure-aware function/class jumps.

### Debugging

- Core: `nvim-dap`, `nvim-dap-ui`, `mason-nvim-dap`, `nvim-dap-go`.
- JS/TS: `nvim-dap-vscode-js` configured with `js-debug-adapter` and
  `pwa-node` launch/attach defaults.
- C/C++: `codelldb` installation via Mason and baseline launch profile
  (`Launch current file (codelldb)`).

### Testing

- `neotest` core with adapters:
  - `neotest-jest`
  - `neotest-vitest`
  - `neotest-gtest`

Notes for C++ tests:

- `neotest-gtest` needs executable mapping per project (use `:ConfigureGtest`
  from the neotest summary window).

### Formatting and linting

- Formatting via `conform.nvim`:
  - JS/TS/JSON/YAML: `prettierd` -> `prettier`
  - C/C++: `clang_format`
  - Lua: `stylua`
- Linting via `nvim-lint`:
  - markdown: `markdownlint`
  - dockerfile: `hadolint`
  - yaml / yaml.helm-values: `yamllint`

Linting is executable-aware for configured linters to avoid noisy diagnostics
when a linter binary is unavailable.

### Project workflow plugins

- `trouble.nvim`: focused diagnostics/issues panel
- `grug-far.nvim`: project-wide search/replace
- `oil.nvim`: optional file editing explorer (does not replace default explorer)
- `cmake-tools.nvim`: CMake build/run/test helpers (lazy and optional)

## Mason-managed tools and servers

This config ensures installation for key tools used by the workflows above,
including:

- `prettierd`, `prettier`, `clang-format`
- `hadolint`, `yamllint`, `markdownlint`, `stylua`
- `js-debug-adapter`, `codelldb`
- configured LSP servers from `servers` table (including `helm_ls`)

Check with `:Mason` and install manually if needed.

## Typical workflows

### JS/TS service workflow

1. Edit with LSP + treesitter context.
2. Run nearest test with `<leader>nr` or file with `<leader>nf`.
3. Debug test or code path with `<leader>nd` / `<F5>`.
4. Use `<leader>sR` for safe project refactors.

### C/C++ workflow

1. Navigate symbols with `<leader>jm/jk/jc/jC`.
2. Build/test with CMake mappings if project uses CMake.
3. Debug using existing DAP keys and select `Launch current file (codelldb)`.
4. Run gtest via neotest after `:ConfigureGtest` setup.

### Kubernetes/Helm workflow

1. Edit manifests with `yamlls` schema-backed completion/validation.
2. Edit charts/templates with Helm support (`helm_ls`, `vim-helm`).
3. Use `<leader>sR` for scoped multi-file YAML refactors.

## Troubleshooting

- Verify startup: `nvim --headless "+qa"`
- Verify health: `nvim --headless "+checkhealth" "+qa"`
- Verify LSP clients in current buffer: `:LspInfo`
- Verify formatter mapping: `:ConformInfo`
- Verify Mason state: `:Mason`
- Re-sync plugins: `:Lazy sync`

If a new feature appears missing, first confirm lazy-loading trigger
(keymap/filetype/command) was actually used.

## Help docs

This repo ships a Vim help file:

- `:help nvim-config`
- `:help nvimn-config`