docs: readme, contributing guide

2026-04-11 16:44:58 -06:00
1 parent 8234872a74
commit fef6672c5e
@@ -1 +1,70 @@
 # Contributing to tiny-debugger.nvim
+
+## Source Control
+
+We use **jj** (Jujutsu), not git. All commits should be made with `jj commit`.
+
+## Adding a New Adapter
+
+1. Create `lua/tiny-debugger/adapters/<language>.lua`
+2. Implement a `register(dap)` function that calls `loader.register()`
+3. Add the module name to the adapters list in `lua/tiny-debugger/adapters/init.lua`
+4. Add the language to the README and vimdoc tables
+
+Example adapter (minimal):
+
+```lua
+local loader = require("tiny-debugger.adapters.init")
+
+local M = {}
+
+function M.register(dap)
+  local binary = loader.find_executable({ "my-debug-adapter" })
+  if not binary then return end
+
+  loader.register(dap, "my-adapter", {
+    type = "executable",
+    command = binary,
+  }, {
+    {
+      type = "my-adapter",
+      request = "launch",
+      name = "Launch file",
+      program = "${file}",
+    },
+  }, { "mylang" })
+end
+
+return M
+```
+
+## Running Tests
+
+```sh
+nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_config.lua' -c 'qa!'
+nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_mode.lua' -c 'qa!'
+nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_keys.lua' -c 'qa!'
+nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_help.lua' -c 'qa!'
+nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_breakpoints.lua' -c 'qa!'
+nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_adapters.lua' -c 'qa!'
+```
+
+## Code Style
+
+- Clean, readable Lua. No metaprogramming tricks.
+- Every file should be short enough to read in one sitting.
+- No abstraction for abstraction's sake.
+- If a plugin does something we can do in <50 lines, we don't add the dependency.
+
+## Dependencies
+
+We depend on exactly five plugins (managed via `vim.pack.add`):
+
+- nvim-dap
+- nvim-dap-ui
+- nvim-nio
+- nvim-dap-virtual-text
+- persistent-breakpoints.nvim
+
+No language-specific plugin dependencies. Adapter configs are inlined as plain
+Lua tables.
@@ -1 +1,125 @@
 # tiny-debugger.nvim
+
+A zero-config debugging experience for Neovim 0.12+. One line of config, full
+IDE-class debugging: inline variable values, hover inspection, persistent
+breakpoints, watch expressions, and modal keybindings that just work.
+
+## Install
+
+```lua
+vim.pack.add("swaits/tiny-debugger.nvim")
+```
+
+That's it. No other config needed.
+
+## What You Get
+
+- **Inline virtual text** — variable values appear right in your source code,
+  updated live as you step
+- **Hover inspection** — press `K` on any expression to see its value
+- **Persistent breakpoints** — survive Neovim restarts, visible in the sign
+  column at all times
+- **Watch expressions** — press `W` to add the expression under your cursor
+- **Scopes panel** — all local/global variables in the current frame
+- **Stack traces** — navigate the call stack, jump to any frame
+- **REPL** — evaluate arbitrary expressions in the debug context
+- **Console** — program stdout/stderr
+- **Modal keybindings** — single-key controls, active only during debug sessions
+- **Help box** — shows all keybindings, re-openable with `?`
+- **Zero-config adapters** for 10+ languages
+
+## UI Layout
+
+```
+┌──────────────────────────────────┬──────────────────┐
+│                                  │ Scopes     (50%) │
+│          Source Code              │                  │
+│                                  ├──────────────────┤
+│     x = 42  -- « virtual text    │ Watches    (25%) │
+│                                  ├──────────────────┤
+│                                  │ Stacks     (25%) │
+├──────────────────────────────────┴──────────────────┤
+│ REPL (50%)               │ Console (50%)            │
+└──────────────────────────┴──────────────────────────┘
+```
+
+## Keybindings
+
+`<leader>d` toggles debug mode. During debug mode:
+
+| Key | Action                 | Mnemonic            |
+|-----|------------------------|---------------------|
+| `c` | Continue               | Continue            |
+| `s` | Step over              | Step                |
+| `d` | Step into              | Descend             |
+| `r` | Step out               | Return              |
+| `C` | Run to cursor          | Continue to cursor  |
+| `x` | Toggle breakpoint      | X marks the spot    |
+| `X` | Conditional breakpoint | Shift-x             |
+| `W` | Watch expression       | Watch               |
+| `K` | Hover / inspect        | LSP hover convention|
+| `E` | Eval in REPL           | Evaluate            |
+| `q` | Terminate session      | Quit                |
+| `R` | Restart session        | Rerun               |
+| `?` | Help popup             | Help                |
+
+`x` and `X` work outside debug mode too.
+
+All navigation keys preserved: `h j k l w b e f / n` etc.
+
+## Supported Languages
+
+| Language        | Adapter         | Binary needed        |
+|-----------------|-----------------|----------------------|
+| Python          | debugpy         | `python -m debugpy`  |
+| JavaScript / TS | js-debug        | `js-debug-adapter`   |
+| Go              | delve           | `dlv`                |
+| C / C++         | codelldb        | `codelldb`           |
+| Rust            | codelldb        | `codelldb`           |
+| Swift           | codelldb        | `codelldb`           |
+| C#              | netcoredbg      | `netcoredbg`         |
+| Java            | java-debug      | `java-debug-adapter` |
+| Kotlin          | kotlin-debug    | `kotlin-debug-adapter`|
+| PHP             | php-debug       | `php-debug-adapter`  |
+| Ruby            | rdbg            | `rdbg`               |
+| Lua (Neovim)    | osv             | one-small-step-for-vimkind |
+
+Adapter binaries are the user's responsibility to install (via mason, system
+package manager, or manually). tiny-debugger configures, it doesn't install.
+
+## Configuration (optional)
+
+```lua
+require("tiny-debugger").setup({
+  help_on_enter = true,       -- show help box when entering debug mode
+  builtin_adapters = true,    -- register built-in language adapters
+
+  keys = {
+    continue = "c",           -- override any key
+    step_over = false,        -- set to false to disable
+  },
+
+  adapters = {
+    zig = { ... },            -- add new language adapters
+  },
+
+  dapui = { ... },            -- override nvim-dap-ui layout
+  virtual_text = { ... },     -- override virtual text settings
+})
+```
+
+## Statusline
+
+```lua
+require("tiny-debugger").active()  -- returns true/false
+```
+
+## Help
+
+```
+:help tiny-debugger
+```
+
+## License
+
+MIT