1 +#
Neovim Configuration — bugabinga 7 +├── init.lua # Main entry point; Neovim 0.11+ required
8 +├── justfile # Build/lint/dev commands (Nushell, not bash)
10 +│ ├── std/ # Standard library (no external deps)
11 +│ │ ├── auto.lua # vim.api.nvim_create_autocmd wrapper
12 +│ │ ├── const.lua # OS/app constants (win32, wsl, os_background)
13 +│ │ ├── dbg/ # Debug logging submodule directory
14 +│ │ │ ├── init.lua # Debug facade (dbg(), dbg.toggle(), dbg.kind())
15 +│ │ │ ├── viewer.lua # Special buffer UI for browsing debug events
16 +│ │ │ ├── file.lua # JSONL file read/write + context detection
17 +│ │ │ ├── format.lua # Format string parser ({N}, {["key"]} placeholders)
18 +│ │ │ ├── kinds.lua # DEBUG/TRACE/ERROR kind definitions (icon, label, color)
19 +│ │ │ └── encode.lua # JSON encoder for debug data
20 +│ │ ├── icon.lua # Nerd font icon map (LSP/completion icons)
21 +│ │ ├── map.lua # Fluent keymap DSL (builder pattern)
22 +│ │ ├── prequire.lua # Protected require with nil-safe proxy
23 +│ │ ├── project.lua # Project root detection (weighted markers)
24 +│ │ ├── puk.lua # Plugin loader (vim.schedule_wrap defer)
25 +│ │ ├── table/ # Table util wrappers (deep_copy, join)
26 +│ │ └── user_command.lua # Fluent user command DSL
27 +│ ├── bugabinga/ # Configuration modules (std + plugins only)
28 +│ │ ├── lsp.lua # LSP config loader (lsp/*.lua auto-discovery)
29 +│ │ ├── format.lua # conform.nvim setup + format keymap
30 +│ │ ├── options/ # Neovim options (keymaps, core, behaviour)
31 +│ │ └── nugu/ # Color theme (palette, dark/light variants)
32 +│ └── patches/ # Built-in Lua function overrides
34 +│ ├── ftplugin/ # File-type specific config
35 +│ ├── queries/ # Treesitter query overrides
36 +│ └── syntax/ # Syntax highlight tweaks
38 +│ └── nugu.lua # Color scheme definition
39 +├── lsp/ # LSP server configs (lua_ls, gopls, etc.)
40 +├── tests/ # PlenaryBusted test suite
41 +│ ├── minimal_init.lua # Test harness (preloads plenary, sets package.path)
42 +│ ├── std/ # Tests for std lib (mirror lua/std structure)
43 +│ └── bugabinga/ # Tests for bugabinga modules
44 +└── test/ # Scratch/test artifacts (d2, svg, etc.)
49 +All commands run via `just` (Nushell, not bash):
51 +| Command | Description |
52 +| ----------------------- | -------------------------------------------------------------------- |
53 +| `just` | List all recipes |
54 +| `just test` | Run full test suite (PlenaryBusted) |
55 +| `just test-file <path>` | Run single test file, e.g. `just test-file tests/std/const_spec.lua` |
56 +| `just refac` | Run ast-grep refactoring (interactive) |
57 +| `just repro` | Reproduce issue with `nvim -u repro.lua` |
58 +| `just nuk` | Delete all Neovim state (cache, data, state) |
59 +| `just puke` | Update plugins from `puk.plugins.nuon` |
63 +- **Framework**: PlenaryBusted
64 + (`nvim --headless -c "packadd plenary" -c "PlenaryBustedDirectory tests/" +q`)
65 +- **Test file naming**: `*_spec.lua` suffix, mirror source path under `tests/`
66 +- **Test harness**: `tests/minimal_init.lua` preloads plenary and sets
68 +- **Module cache**: Invalidate with `package.loaded['module'] = nil` before
72 + before_each(function()
73 + package.loaded['std.const'] = nil
77 +##
Architecture Rules 79 +1. **`std/`** — May only depend on itself and Neovim APIs. No plugins.
80 +2. **`lua/bugabinga/`** — May depend on `std`, plugins, and Neovim APIs.
81 +3. **`lua/patches/`** — Overrides to built-in Neovim Lua functions (loaded
83 +4. **Plugin config** — Lives in `lua/bugabinga/` alongside native config.
87 +###
std.auto(group_name) 89 +Creates autocmd group; returns function to register autocmds.
92 +local auto = require 'std.auto'
94 + events = 'VimEnter',
95 + command = function() print 'hello' end,
101 +Fluent keymap builder; modes are chainable.
104 +local map = require 'std.map'
105 +map.normal { keys = 'gd', command = vim.lsp.buf.definition }
106 +map.insert { keys = '<c-s>', command = vim.lsp.buf.signature_help }
109 +###
std.user_command 111 +Fluent user command builder.
114 +local user_command = require 'std.user_command'
115 +user_command.MyCommand 'Does something' (function() print 'ran' end)
120 +Plugin loader with `defer` for lazy loading.
123 +local puk = require 'std.puk'
124 +puk.defer 'mini.pick' (function(pick) pick.setup {} end)
125 +-- Direct require for eager loading:
126 +-- local plugin = puk 'plugin_name'
131 +Protected require; returns nil-safe proxy on failure.
134 +local prequire = require 'std.prequire'
135 +prequire('missing', function(foo) foo.setup() end) -- no crash
140 +Debug logging via `vim.g.bugabinga_debug_mode`. All events written to
141 +`stdpath('state')/bugabinga_config_debug.jsonl` (JSONL).
144 +local dbg = require 'std.dbg'
145 +dbg 'hello {1}' { 'world' } -- DEBUG event
146 +dbg.kind('ERROR', 'something broke') -- ERROR event
147 +dbg.toggle() -- toggle debug mode on/off
148 +dbg.get() -- returns boolean
151 +####
Placeholder Syntax 153 +| Format | Meaning |
154 +| ----------- | ---------------------------------------------- |
155 +| `{N}` | Positional argument N (1-indexed) |
156 +| `{["key"]}` | Table key (bracket notation for special chars) |
160 +- `dbg('sum: {1}', a + b)` — positional
161 +- `dbg('name: {1}, value: {2}', name, value)` — indexed
162 +- `dbg('user: {["user.name"]}', user)` — bracket notation
166 +| Command | Description |
167 +| ---------------- | ------------------------------------ |
168 +| `:DbgModeToggle` | Toggle `vim.g.bugabinga_debug_mode` |
169 +| `:DbgViewToggle` | Open or close the debug event viewer |
170 +| `:DbgOpenFile` | Open the raw JSONL log file |
174 +- `{1}` is the first positional argument. `{}` is NOT valid — format parsing
179 +###
Formatting (.editorconfig defaults) 181 +- **Indent**: 2 spaces (no tabs)
182 +- **Quotes**: Single quotes (`'string'`)
183 +- **Line length**: Max 120 characters
184 +- **End of line**: LF (not CRLF)
185 +- **Trailing commas**: Smart (keep in tables)
186 +- **Final newline**: Yes
190 +- **No comments** unless explicitly requested by user
191 +- **Module pattern**: `return setmetatable({...}, {__index = ...})` or
193 +- **Global table shadowing**: Modules do `local table = require 'std.table'`
194 + (not `table = require...`)
195 +- **Input validation**: Use `vim.validate` at function entry points
196 +- **Error handling**: Prefer `pcall` + proxy objects (`std.prequire` pattern)
198 +- **Metatable DSLs**: Builder/method-chaining patterns in `std.map`,
199 + `std.user_command`, `std.auto`
201 +###
Naming Conventions 203 +- **Files**: snake_case (`statusline.lua`, `lua_ls.lua`)
204 +- **Functions/variables**: snake_case (`find_root`, `git_branch`)
205 +- **Modules**: snake_case (`require 'std.project'`)
206 +- **Test files**: `*_spec.lua` suffix, mirror source path
207 +- **Constants**: SCREAMING_SNAKE_CASE for true constants (`MAX_TRAVERSAL_COUNT`)
208 +- **Private locals**: Prefix with `_` (`_internal_helper`)
210 +##
Plugin Management 212 +- **Plugin list**: `puk.plugins.nuon` (Nushell data notation, declarative)
213 +- **Plugin manager**: `puk.nu` (custom, out-of-band)
214 +- **Lazy loading**: `puk.defer 'plugin'` schedules require on
215 + `vim.schedule_wrap`
216 +- **Plugin modules**: Each plugin gets a `require 'bugabinga.<plugin>'` entry in
219 +##
LSP Configuration 221 +- **Server files**: Each in `lsp/<name>.lua` (auto-discovered via
222 + `vim.api.nvim_get_runtime_file 'lsp/*.lua'`)
223 +- **LSP enable**: `vim.lsp.enable(servers)` loads all configs
224 +- **Lua LS**: Configured with LuaJIT runtime, `vim` global, luv library
225 +- **Attach**: `LspAttach` autocmd calls `lsp_attach()` for buffer-local keymaps
229 +- **`just` requires Nushell** (`nu`), not bash or zsh
230 +- **Version gate**: `init.lua` enforces Neovim 0.11; early return on mismatch
231 +- **Debug mode**: Set `vim.g.bugabinga_debug_mode = true` or `NVIM_PROFILE=1`
233 +- **`std.map` modes**: Must chain modes or provide full mode table; empty modes
234 + defaults to `normal`
235 +- **`puk.defer` is async**: The callback runs on `vim.schedule_wrap` — not
237 +- **`std.project` caching**: Results cached; clear
238 + `require('std.project').cache` if needed
239 +- **`lua_ls` diagnostics globals**: `vim` is a declared global (not an error)
240 +- **Conform formatexpr**: Set via `vim.o.formatexpr` in `format.lua`; format
242 +- **Test isolation**: Each test file should handle `package.loaded` cleanup in
243 + `before_each`/`after_each`
244 +- **Windows WSL**: `const.lua` forces `os_background = 'light'` on Win/WSL2
245 +- **`dbg()` placeholder syntax**: `{}` is NOT valid; use `{1}` for first
246 + positional argument (empty `{}` will error in format parsing)