Complete config migration cleanup
Retire legacy files and migration fixtures, move runtime state out of the repository, and migrate Tree-sitter and textobjects to their Neovim 0.12-compatible main branches.
This commit is contained in:
parent
f35ad357bd
commit
f8f478a985
99 changed files with 288 additions and 5473 deletions
255
AGENTS.md
255
AGENTS.md
|
|
@ -1,213 +1,70 @@
|
|||
# AGENTS: Neovim Config Migration
|
||||
# AGENTS: Neovim Configuration
|
||||
|
||||
Scope: applies to the entire `~/.config/nvim` directory tree.
|
||||
Scope: the entire `~/.config/nvim` repository.
|
||||
|
||||
This repository is being migrated to a modern, minimal Neovim setup driven by Lua and lazy.nvim. Follow these rules when making changes.
|
||||
## Current setup
|
||||
|
||||
## Goals
|
||||
- Modern Lua-first config; avoid Vimscript unless explicitly requested.
|
||||
- Keep it minimal, fast, and maintainable.
|
||||
- Base plugin management on `lazy.nvim` with modular plugin specs.
|
||||
- Support Telescope navigation, netrw for tree browsing, previews, and file operations, LSP, native completion, Treesitter, Copilot, and sane UX defaults.
|
||||
- Native project-local configuration via `exrc` + `secure` (no external config plugins).
|
||||
This is the active, daily-use Neovim 0.12 configuration. It is Lua-first,
|
||||
managed with lazy.nvim, and intended to remain small, fast, and maintainable.
|
||||
|
||||
## Do Not Reintroduce
|
||||
- Custom Vimscript tabline/statusline, foldtext, UI hacks.
|
||||
- Legacy autocommands toggling cursorline/column per window.
|
||||
- CoC or CoC-specific config.
|
||||
- Neo-tree (skipped in favor of netrw for navigation).
|
||||
- Providers for ruby/perl/node (disable unless required by a plugin).
|
||||
- Auto-reload vimrc-on-write templates.
|
||||
- `cursorcolumn` and old folding logic not related to UFO.
|
||||
- neoconf plugin (incompatible with Neovim 0.11+, use native exrc instead).
|
||||
- Motion plugins like leap.nvim or flash.nvim (not needed).
|
||||
- Markdown rendering plugins (skipped entirely).
|
||||
The main workflows are:
|
||||
|
||||
## Repository Structure (target)
|
||||
```
|
||||
~/.config/nvim/
|
||||
├── init.lua -- entrypoint; bootstraps lazy.nvim and loads Lua modules
|
||||
└── lua/
|
||||
├── settings.lua -- non-plugin options
|
||||
├── keymaps.lua -- non-plugin keymaps
|
||||
├── autocmds.lua -- non-plugin autocommands
|
||||
├── abbreviations.lua -- insert-mode abbreviations
|
||||
├── completion.lua -- native insert-mode and LSP completion
|
||||
├── netrw-config.lua -- netrw configuration
|
||||
├── netrw-preview.lua -- live file previews and directory summaries
|
||||
├── utils.lua -- helpers (only if needed)
|
||||
└── plugins/ -- one file per plugin or domain
|
||||
├── telescope.lua
|
||||
├── treesitter.lua
|
||||
├── lsp.lua
|
||||
├── copilot.lua
|
||||
├── ufo.lua
|
||||
├── gitsigns.lua
|
||||
├── conform.lua
|
||||
├── nvim-lint.lua
|
||||
├── mason.lua
|
||||
├── mason-lspconfig.lua
|
||||
├── mason-tool-installer.lua
|
||||
├── comment.lua
|
||||
├── surround.lua
|
||||
├── autopairs.lua
|
||||
└── indent-blankline.lua
|
||||
├── after/
|
||||
│ ├── ftplugin/
|
||||
│ │ └── php.lua -- PHP-specific settings (includeexpr for gf)
|
||||
│ └── queries/ -- Custom Treesitter queries
|
||||
│ ├── css/
|
||||
│ │ └── highlights.scm
|
||||
│ └── html/
|
||||
│ └── highlights.scm
|
||||
├── templates/
|
||||
│ └── template.sh -- Shell script template
|
||||
└── legacy/ -- Archived Vimscript config (reference only)
|
||||
```
|
||||
- netrw for tree browsing, previews, and file operations
|
||||
- Telescope for fuzzy files, grep, buffers, and symbols
|
||||
- native `vim.lsp.config()` / `vim.lsp.enable()` configuration
|
||||
- native insert-mode completion and snippets
|
||||
- Copilot inline suggestions, separate from the completion menu
|
||||
- Tree-sitter, Conform, nvim-lint, Gitsigns, and nvim-ufo
|
||||
- native `nvim.undotree`
|
||||
- project-local `.nvim.lua` files through native `exrc` + `secure`
|
||||
|
||||
## Coding Conventions
|
||||
- Use Lua APIs: `vim.opt`, `vim.api.nvim_create_autocmd`, `vim.keymap.set`.
|
||||
- No inline Vimscript or `vim.cmd` blocks unless strictly necessary.
|
||||
- Keep plugin configuration self-contained in its plugin spec file.
|
||||
- Prefer small, readable modules and minimal configuration over heavy customization.
|
||||
- Keymaps: use `vim.keymap.set` with `{ silent = true, noremap = true }` defaults unless otherwise required.
|
||||
- Autocommands: group via `vim.api.nvim_create_augroup` and create specific, narrowly scoped autocmds.
|
||||
- Avoid global state; return tables from modules and plugin specs.
|
||||
`README.md` documents the user-facing workflows and keymaps. `LOG.md` records
|
||||
architectural decisions.
|
||||
|
||||
## Plugin Management (lazy.nvim)
|
||||
- Each plugin lives in `lua/plugins/<name>.lua` and returns a spec table.
|
||||
- Use `opts = {}` for default options and `config = function(_, opts) ... end` for setup.
|
||||
- Do not install any plugin not listed without explicit user confirmation (proposal and rationale are welcome).
|
||||
- Rejected: `folke/neoconf.nvim` (incompatible with Neovim 0.11+ vim.lsp.config API).
|
||||
## Maintenance rules
|
||||
|
||||
## Required Plugin Categories
|
||||
- Core: `nvim-lspconfig`; use Neovim 0.12 native insert-mode/LSP completion and snippets instead of the nvim-cmp stack.
|
||||
- Navigation: `telescope.nvim` + `telescope-fzf-native.nvim`; netrw is the sole file explorer.
|
||||
- Treesitter: `nvim-treesitter`, `nvim-treesitter-textobjects`, `nvim-ts-autotag`.
|
||||
- UX/Editing: `Comment.nvim`, `nvim-surround`, `nvim-autopairs`, `indent-blankline.nvim`, `nvim-ufo`; use Neovim 0.12's native optional `nvim.undotree` package.
|
||||
- Git: `gitsigns.nvim`.
|
||||
- Copilot: `copilot.lua` with inline suggestions; do not integrate Copilot into the native completion popup.
|
||||
- Formatting/Linting: `conform.nvim`, `nvim-lint`.
|
||||
- LSP Management: `mason.nvim`, `mason-lspconfig.nvim`, `mason-tool-installer.nvim`.
|
||||
- Prefer Lua APIs such as `vim.opt`, `vim.keymap.set`, and
|
||||
`vim.api.nvim_create_autocmd`; use Vimscript only when a native integration
|
||||
requires it.
|
||||
- Keep non-plugin behavior in focused modules under `lua/`.
|
||||
- Keep each plugin specification self-contained under `lua/plugins/`.
|
||||
- Continue using lazy.nvim; do not mix plugin managers without an explicit
|
||||
decision to migrate.
|
||||
- Do not add a plugin without explicit user confirmation.
|
||||
- Keep netrw as the sole file explorer and Telescope as the fuzzy navigator.
|
||||
- Use Neovim's native completion rather than reintroducing nvim-cmp or LuaSnip.
|
||||
- Keep Copilot as inline suggestions rather than a completion-menu source.
|
||||
- Use the modern LSP API; do not restore legacy `lspconfig.setup()` calls or
|
||||
neoconf.
|
||||
- Preserve native project-local configuration through `exrc` + `secure`.
|
||||
- Keep providers for Ruby, Perl, and Node disabled unless an active plugin
|
||||
requires one.
|
||||
- Preserve the existing Lua tabline, but do not restore the old Vimscript
|
||||
tabline/statusline, foldtext, cursorline/column window hacks, CoC, Neo-tree,
|
||||
motion plugins, or Markdown rendering plugins unless the user explicitly
|
||||
revisits those decisions.
|
||||
- Preserve unrelated user changes and keep patches narrowly scoped.
|
||||
|
||||
## Workflow Requirements to Preserve
|
||||
- Netrw for visual context and project structure browsing (tree view, preview splits).
|
||||
- Telescope for fuzzy finding (files, grep, buffers, LSP symbols).
|
||||
- Netrw for file manipulation as well as browsing, preserving the same workflow on remote systems.
|
||||
- LSP for navigation (gd, gr, K, etc.).
|
||||
- Heavy HTML/PHP/JS/Markdown usage (WordPress plugin dev) — prioritize these languages in LSP/Treesitter.
|
||||
- Format-on-save with toggle capability.
|
||||
- Project-local configuration via `.nvim.lua` files.
|
||||
## Documentation and validation
|
||||
|
||||
## Behaviours to Keep (modernized)
|
||||
- Abbreviations: `adn→and`, `waht→what`, `tehn→then`, `functin→function`, `positin→position`.
|
||||
- Templates: auto-populate `.sh` from template.
|
||||
- Whitespace highlighting (use modern alternatives, e.g., `listchars`, plugins if needed).
|
||||
- Persistent folds (prefer `nvim-ufo`).
|
||||
- Spell & text: `spelllang=en_gb`, custom `listchars`, `showbreak`.
|
||||
- Keyword characters: `iskeyword+=$` (for PHP/shell variables), `iskeyword+=-` (for CSS/HTML/config files).
|
||||
- Update `README.md` whenever user-facing behavior or keymaps change.
|
||||
- Update its configuration section when formatter, linter, or tool resolution
|
||||
changes.
|
||||
- Record significant architectural decisions in `LOG.md`.
|
||||
- After configuration or plugin changes, run at least:
|
||||
|
||||
## Current Status (Phase 14 In Progress)
|
||||
- ✅ Phase 1-2: Archive legacy, bootstrap lazy.nvim
|
||||
- ✅ Phase 3: Core editing & LSP (native exrc + vim.lsp.config migration complete)
|
||||
- ✅ Phase 4: Navigation (Telescope and netrw)
|
||||
- ✅ Phase 5: Treesitter (parsers, textobjects, autotag)
|
||||
- ✅ Phase 6: UX/Editing (Comment, surround, autopairs, indent guides, UFO, native Undotree)
|
||||
- ✅ Phase 7: Git integration (Gitsigns)
|
||||
- ✅ Phase 8: Copilot integration (copilot.lua inline suggestions)
|
||||
- ✅ Phase 9: Formatting & Linting (conform.nvim, nvim-lint, Mason tool installer)
|
||||
- ✅ Phase 10: Migrate kept behaviors (abbreviations, templates, custom Treesitter queries)
|
||||
- ✅ Phase 11: Modern Paper Tonic colorscheme
|
||||
- ⏳ Phase 12: Cleanup and validation (repository cleanup and automated checks complete; interactive workflow checks remain)
|
||||
- ✅ Phase 13: Neovim 0.12.6 activated and native editing workflows validated
|
||||
- ✅ Phase 13.9: Native Undotree and completion consolidation complete
|
||||
- ⏳ Phase 14: Netrw live previews and directory summaries implemented; interactive validation remains
|
||||
```bash
|
||||
nvim --headless -c 'lua print("Config loads")' -c 'quitall'
|
||||
```
|
||||
|
||||
## Migration Notes
|
||||
- Do not edit legacy Vimscript files except to extract settings to Lua. Keep them intact until migration completes.
|
||||
- Introduce `init.lua` and bootstrap `lazy.nvim` before adding plugins.
|
||||
- Disable unnecessary providers early: `vim.g.loaded_ruby_provider = 0`, etc.
|
||||
- Keep startup fast; avoid unnecessary autoloading or heavy defaults.
|
||||
- When cleaning, archive existing files into a `legacy/` folder within this config instead of deleting. Maintain a brief index if helpful.
|
||||
- For relevant changes, also exercise the affected workflow interactively.
|
||||
|
||||
## Validation
|
||||
- Ensure Neovim starts without errors and with minimal startup time.
|
||||
- Verify Telescope navigation, netrw browsing and file operations, LSP basics, and completion.
|
||||
- Keep plugin count tight; remove anything unused.
|
||||
## History
|
||||
|
||||
## Key Decisions & Architecture
|
||||
|
||||
### LSP Configuration
|
||||
- **Modern API (Neovim 0.11+)**: Uses `vim.lsp.config()` + `vim.lsp.enable()`, NOT `require('lspconfig')[server].setup()`
|
||||
- **Project-local config**: Native `exrc` + `secure` (no neoconf - incompatible with 0.11+)
|
||||
- **Config format**: `.nvim.lua` files return `{ lsp = { [server_name] = { settings = {...} } } }`
|
||||
- **Security**: `secure` mode prompts user to trust `.nvim.lua` files (one-time per file hash)
|
||||
- **Settings loading**: `LspAttach` securely reads `.nvim.lua` from the client's actual `root_dir` (not cwd)
|
||||
- **PHP**: intelephense with `single_file_support = false`, uses `environment.includePaths` for external libs
|
||||
|
||||
### Navigation Strategy
|
||||
- **netrw**: Visual context, tree view, preview splits (horizontal 50/50 below)
|
||||
- **Telescope**: Fuzzy finding (files, grep, buffers, LSP symbols)
|
||||
- **netrw**: Sole file explorer for tree browsing, previews, and file operations
|
||||
- **PHP gf enhancement**: Custom `includeexpr` in `after/ftplugin/php.lua` for WordPress/PHP patterns
|
||||
|
||||
### Formatting & Linting
|
||||
- **Formatters**: prettier, phpcbf, stylua, ruff_format (project-local → Mason → global)
|
||||
- **Linters**: eslint_d, phpcs, markdownlint, plus Ruff through LSP
|
||||
- **Format-on-save**: Enabled by default, toggle with `<leader>lt`
|
||||
- **Philosophy**: Formatters are source of truth; Neovim settings match formatter rules per filetype
|
||||
|
||||
### Treesitter
|
||||
- **Parsers**: lua, vim, vimdoc, php, html, javascript, typescript, tsx, css, scss, json, markdown, bash, regex
|
||||
- **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag
|
||||
- **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm`
|
||||
|
||||
### Session Management
|
||||
- **Auto-load**: On `VimEnter`, loads `Session.vim` if it exists (unless files specified on command line)
|
||||
- **Auto-save**: On `VimLeavePre`, saves to `Session.vim` if it already exists
|
||||
- **Manual control**: Create with `:mksession` to enable; delete to disable
|
||||
- **Per-directory**: Sessions are opt-in and workspace-specific
|
||||
|
||||
## Developer Workflows
|
||||
|
||||
### Testing Changes
|
||||
```bash
|
||||
# Quick syntax check
|
||||
nvim --headless -c 'lua print("Config loads")' -c 'quitall'
|
||||
|
||||
# Check LSP status in test workspace
|
||||
cd ~/.config/nvim/WORKSPACE_TEST
|
||||
nvim site/external.php # Then :LspInfo
|
||||
|
||||
# Validate goto-definition for external libs
|
||||
# In external.php, cursor on Util::greetExternal, press gd
|
||||
```
|
||||
|
||||
### Validation Workspaces
|
||||
- `WORKSPACE_TEST/`: PHP project with `.nvim.lua` and `.git`
|
||||
- `EXTERNAL_TEST/`: External library referenced via includePaths
|
||||
- Test that `gd` resolves symbols in EXTERNAL_TEST from WORKSPACE_TEST
|
||||
|
||||
## Common Issues
|
||||
|
||||
### lua_ls Won't Start
|
||||
Mason-installed lua_ls may fail with missing `libbfd-2.38-system.so`. Install via system package manager instead.
|
||||
|
||||
### LSP Root Detection
|
||||
If parent repo picked as root, create empty `.git` or `.nvimroot` marker in intended workspace root.
|
||||
|
||||
### Duplicate gd Results (Fixed)
|
||||
Was caused by settings loading at wrong time; fixed by using `LspAttach` autocmd with actual `root_dir`.
|
||||
|
||||
## Process
|
||||
- Before large changes, update the task plan via the CLI `update_plan` tool.
|
||||
- Keep the live checklist in `MIGRATION_PLAN.md:1` up to date and in sync with changes.
|
||||
- After any config or plugin change, immediately update `MIGRATION_PLAN.md` (check off items, add notes, or adjust next steps).
|
||||
- After any change or decision, also update `LOG.md:1` (decisions log and design docs).
|
||||
- **After adding/removing/editing any keymaps**, immediately update `README.md` with the change (add new entries, remove deleted mappings, or update descriptions).
|
||||
- **After changing formatter/linter configuration, standards, or tool resolution**, immediately update the "Configuration" section in `README.md` (update tool lists, override instructions, or behavior descriptions).
|
||||
- At the start of each phase, confirm scope and priorities for that phase.
|
||||
- Execute phases via subphases (`N.x`), where each bullet under a phase is its own implement-and-test step (e.g., Phase 3.1, 3.2, 3.3, 3.4).
|
||||
- Record decisions and rationale in `LOG.md:1` as they're made.
|
||||
- Keep PR-sized patches; avoid broad unrelated edits.
|
||||
- Document non-obvious choices in commit messages or short comments near the code that needs it.
|
||||
This configuration began as a large Vimscript setup with bundled plugins and
|
||||
was incrementally rebuilt as a modern Lua configuration. The migration covered
|
||||
lazy.nvim, native LSP and project configuration, native completion and
|
||||
Undotree, Telescope, a netrw-centered explorer workflow, Tree-sitter, Copilot,
|
||||
formatting, linting, and the Paper Tonic colorscheme. After sustained daily use
|
||||
on Neovim 0.12.6, the migration was declared complete on 2026-10-28. The
|
||||
decision history remains in `LOG.md` and Git history.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue