# Migration Plan: none-ls → conform.nvim

**Date:** 2026-01-12  
**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 (none-ls):**
- ✅ prettier (JS/TS/CSS/JSON/HTML/Markdown)
- ✅ stylua (Lua)
- ❌ phpcbf (PHP) - broken, using custom autocmd workaround

**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) - **verify 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 (if needed)
- [ ] Update MIGRATION_PLAN.md status
- [ ] 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