nvim/CONFORM_MIGRATION.md

Migration Plan: none-ls → conform.nvim

Date: 2026-01-12
Status: ✅ COMPLETED
Reason: none-ls's phpcbf formatter is buggy (adds blank lines). conform.nvim is more modern, doesn't use LSP overhead, better maintained.

Current State

Formatting (conform.nvim):

• ✅ prettier (JS/TS/CSS/JSON/HTML/Markdown)
• ✅ stylua (Lua)
• ✅ phpcbf (PHP) with WordPress standard

Linting (nvim-lint):

• phpcs, eslint_d, markdownlint

LSP (lspconfig):

• Language features (autocomplete, goto-def, hover, etc.)

Migration Checklist

Phase 1: Setup conform.nvim

• Create lua/plugins/conform.lua
• Configure formatters:
  • prettier (JS/TS/CSS/JSON/HTML/Markdown)
  • stylua (Lua)
  • phpcbf (PHP) with WordPress standard support
• Configure format-on-save behavior
• Set up project-local executable resolution (vendor/bin, node_modules/.bin, Mason, global)
• Add keymaps for manual formatting (<leader>lf, <leader>lt)

Phase 2: Remove none-ls

• Delete lua/plugins/none-ls.lua
• Remove none-ls from lazy-lock.json (happens automatically on :Lazy sync)
• Remove the custom phpcbf autocmd workaround (no longer needed)

Phase 3: Testing

• Test prettier formatting (JS/TS/CSS files)
• Test stylua formatting (Lua files)
• Test phpcbf formatting (PHP files) - verified NO blank lines added
• Test format-on-save toggle (<leader>lt)
• Test manual format (<leader>lf)
• Test project-local formatter detection
• Verify phpcs.xml is respected when present

Phase 4: Documentation

• Update README.md Configuration section
• Update AGENTS.md Process section (plugin list, formatting tools)
• Update MIGRATION_PLAN.md status (Phase 9.2)
• Update LOG.md with decision and rationale

Expected Benefits

1. No more blank line bug - conform calls phpcbf cleanly without none-ls's buggy preprocessing
2. No LSP overhead - formatters run as simple shell commands
3. Better maintained - conform.nvim is actively developed
4. Cleaner architecture - clear separation: LSP (features), nvim-lint (diagnostics), conform (formatting)
5. Easier debugging - simpler execution path, better error messages

Rollback Plan

If conform.nvim has issues:

1. Restore lua/plugins/none-ls.lua from git
2. Keep the custom phpcbf autocmd for PHP
3. Run :Lazy sync to reinstall none-ls

Notes

• conform.nvim has built-in support for all our formatters (prettier, stylua, phpcbf)
• It handles executable resolution similarly to our find_executable() helper
• Format-on-save can be toggled per-buffer or globally
• Visual range formatting supported out of the box