nvim/MIGRATION_PLAN.md

Neovim Migration Checklist

Source of truth for the step-by-step rebuild. Keep this concise and up to date. See details in neovim-migration-guide.md.

Phase 0 — Ground Rules

• Create AGENTS.md with rules

Phase 1 — Clean & Archive Legacy Config

Phase 1.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 1.2 — Inventory legacy files

• Inventory existing Vimscript, plugin files, and directories

Phase 1.3 — Create archive location

• Create legacy/ archive folder within this config

Phase 1.4 — Move legacy files into archive

• Move legacy init files and plugin directories into legacy/ (do not delete)

Phase 1.5 — Document archived contents

• Optionally add legacy/README.md noting what was archived

Phase 1.6 — Preserve selected directories

• Keep undodir, spell, view, UltiSnips, templates as-is for now (review later)

Phase 2 — Bootstrap

Phase 2.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 2.2 — Scaffold Lua config skeleton

• Scaffold Lua config skeleton (init.lua, lua/settings.lua, lua/keymaps.lua, lua/autocmds.lua, lua/utils.lua, lua/plugins/)

Phase 2.3 — Bootstrap lazy.nvim

• Bootstrap lazy.nvim plugin manager

Phase 2.4 — Disable unused providers

• Disable unused providers (ruby, perl, node)

Phase 2.5 — Ensure lazy boots without specs

• Ensure lazy boots without specs (add empty lua/plugins/init.lua)

Phase 3 — Core Editing & LSP

Phase 3.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: PHP LSP = intelephense
• Decision: Enable Markdown LSP = marksman
• Decision: Use legacy listchars and showbreak values
• Decision: Support per‑project config for intelephense.includePaths
• Decision: No direnv fallback for local config

Phase 3.2 — Non-plugin settings to Lua

• Port non-plugin settings to Lua (options, listchars, showbreak, spelllang=en_gb)

Phase 3.3 — Core completion stack

• Add core completion stack: nvim-cmp, cmp-nvim-lsp, cmp-buffer, cmp-path, LuaSnip

Phase 3.4 — Project‑local configuration (neoconf)

• Confirm scope and priorities for this subphase
• Choose approach: use folke/neoconf.nvim (replaces custom loader)
• Add folke/neoconf.nvim plugin spec and minimal setup
• Document .neoconf.json usage and example in README
• Verify neoconf merges settings into lspconfig
• Wire intelephense.environment.includePaths via .neoconf.json
• Create validation workspaces: WORKSPACE_TEST/ and EXTERNAL_TEST/ with sample PHP files
• Enable LSP debug notifications during validation and remove them after verifying roots

Phase 3.7 — Clean LSP config

• Remove debug/helper logic from LSP config
• Use non-deprecated per-server setup (no top-level lspconfig table access)

Phase 3.8 — Validate Neoconf includePaths (temporary)

• Temporarily inject intelephense.environment.includePaths via lspconfig for WORKSPACE_SIMPLE to validate goto-definition
• After validation, remove the temporary injection and rely on neoconf

Phase 3.9 — Neoconf + Root Fix (BLOCKER)

Phase 3.9.1 — Confirm neoconf merge hook

• Ensure neoconf lspconfig integration applies before server setup (validate with jsonls in WORKSPACE_SIMPLE)
• Decide schema for intelephense settings (nested settings.intelephense.environment.includePaths)

Phase 3.9.2 — Temporary merge shim (if needed)

• Implement minimal per-server merge from .neoconf.json → lspconfig.intelephense.settings at setup-time (remove later if neoconf resolves)

Phase 3.9.3 — Robust PHP root resolver

• Implement explicit root_dir resolver (prefer .neoconf.json, composer.json, .nvimroot, then nearest .git) using vim.fs.find
• Keep single_file_support = false for intelephense

Phase 3.9.4 — Validate in WORKSPACE_SIMPLE

• :LspInfo shows correct root
• gd works for local and any configured includePaths

Phase 3.9.5 — Validate in WORKSPACE_TEST + EXTERNAL_TEST

• With forced workspace root, gd still resolves external library symbols via includePaths
• Confirm behavior after client restart and fresh session

Phase 3.9.6 — Decision: rooter plugin (optional)

• If root resolution remains brittle, propose adding a rooter plugin (requires approval), tuned for tab-per-context

Phase 3.9.7 — Finalize approach

• If neoconf merge works reliably, remove temporary shim; otherwise retain shim and document
• Document root marker guidance (.nvimroot) and includePaths best practices

Phase 3.5 — LSP minimal defaults

• Add nvim-lspconfig with minimal defaults (no over-configuration)
• Add minimal LSP on-attach keymaps (gd, gr, K, gD, gI)
• Add global LSP keymaps with fallback in lua/keymaps.lua
• InteIephense root guard: enforce root_dir priority (.neoconf.json, composer.json, .nvimroot, .git) and set single_file_support=false

Phase 3.6 — LSP server management (Mason)

• Confirm scope and priorities for this subphase
• Add williamboman/mason.nvim and williamboman/mason-lspconfig.nvim
• Ensure servers installed: lua_ls, tsserver, html, cssls, jsonls, bashls, marksman, intelephense
• Keep our custom per-server setup; use Mason only for installation
• Improve root detection to include .neoconf.json

Phase 4 — Navigation

Phase 4.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 4.2 — Neo-tree setup

• Add neo-tree.nvim with per-tab roots, sidebar toggle, floating view, and preview keymap (no buffer pollution)

Phase 4.3 — Telescope setup

• Add telescope.nvim (+ optional telescope-fzf-native.nvim) and basic pickers

Phase 5 — Treesitter

Phase 5.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 5.2 — Base Treesitter

• Add nvim-treesitter with incremental selection, highlighting

Phase 5.3 — Treesitter textobjects

• Add nvim-treesitter-textobjects

Phase 5.4 — Treesitter autotag

• Add nvim-ts-autotag

Phase 6 — UX / Editing

Phase 6.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 6.2 — Comment.nvim

• Add numToStr/Comment.nvim

Phase 6.3 — Surround

• Add kylechui/nvim-surround

Phase 6.4 — Autopairs

• Add windwp/nvim-autopairs

Phase 6.5 — Indent guides

• Add lukas-reineke/indent-blankline.nvim

Phase 6.6 — Motion (leap/flash)

• Add ggandor/leap.nvim or folke/flash.nvim

Phase 6.7 — Folding (UFO)

• Add kevinhwang91/nvim-ufo for folding

Phase 6.8 — Optional: Undotree

• (Optional) Add mbbill/undotree

Phase 7 — Git, Markdown, Copilot, Formatting

Phase 7.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 7.2 — Git

• Add lewis6991/gitsigns.nvim

Phase 7.3 — Markdown

• Add render-markdown.nvim

Phase 7.4 — Copilot

• Add zbirenbaum/copilot.lua + copilot-cmp

Phase 7.5 — Formatting

• Add nvimtools/none-ls.nvim with minimal formatters/linters

Phase 8 — Migrate Kept Behaviours

Phase 8.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 8.2 — Abbreviations

• Abbreviations: adn→and, waht→what, tehn→then, functin→function, positin→position

Phase 8.3 — Templates

• Templates: auto-populate new .sh from template

Phase 8.4 — Whitespace highlighting

• Whitespace highlighting (modern approach)

Phase 8.5 — Persistent folds

• Persistent folds (via UFO)

Phase 9 — Cleanup & Validation

Phase 9.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 9.2 — Retire legacy files

• Retire legacy Vimscript files (keep for reference until verified)

Phase 9.3 — Startup performance

• Validate startup performance (no errors, fast launch)

Phase 9.4 — Tab workflow validation

• Validate tab-per-context workflow with Neo-tree

Phase 9.5 — Navigation validation

• Validate Telescope navigation + LSP jumps

Phase 9.6 — Language tooling validation

• Validate HTML/PHP/JS/Markdown tooling

---

Notes:

• Keep plugin specs minimal; configure in their own lua/plugins/*.lua files.
• Avoid adding plugins not listed in the guide unless explicitly requested.
• Prefer simple defaults; only add settings that clearly improve workflow.
• Plugin approval policy: unlisted plugins may be proposed, but must be explicitly confirmed before installation.

Known Issues / Follow-ups (tracked by Phase 3.9):

• lua-language-server (lua_ls) from Mason failed to start due to missing shared library libbfd-2.38-system.so. Options:
  • Install lua-language-server via system package manager compatible with your distro.
  • Provide the required libbfd or adjust symlink to match expected soname.
  • Skip lua_ls for now; neoconf validation can be done with other servers (e.g., jsonls) and PHP (intelephense).
• LSP root detection: In some cases, the parent repository is picked as the root (e.g., when a workspace lives inside another repo). Workaround: create an empty .git directory (or a marker like .nvimroot) in the intended workspace root to pin the project root for LSPs.
• Neoconf merge + root correctness are a blocker for migration. Address via Phase 3.9 subphases above.