diff --git a/AGENTS.md b/AGENTS.md index 6641cd8..19c22dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,7 +53,8 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu ## Plugin Management (lazy.nvim) - Each plugin lives in `lua/plugins/.lua` and returns a spec table. - Use `opts = {}` for default options and `config = function(_, opts) ... end` for setup. -- Only include plugins listed in the migration guide unless explicitly approved. +- Do not install any plugin not listed without explicit user confirmation (proposal and rationale are welcome). +- Approved additions: `folke/neoconf.nvim` for project-local configuration. ## Required Plugin Categories - Core: `nvim-lspconfig`, `nvim-cmp`, `cmp-nvim-lsp`, `cmp-buffer`, `cmp-path`, `LuaSnip`. @@ -93,9 +94,11 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu ## 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). - - 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). +- 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 `README.md:1` (decisions log and design docs). +- 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 `README.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. diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 90ae673..ba760ea 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -50,6 +50,7 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date. - [x] Decision: Enable Markdown LSP = `marksman` - [x] Decision: Use legacy `listchars` and `showbreak` values - [x] Decision: Support per‑project config for `intelephense.includePaths` +- [x] 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) @@ -57,12 +58,13 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date. ## 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 +## Phase 3.4 — Project‑local configuration (neoconf) - [ ] Confirm scope and priorities for this subphase -- [ ] Choose local config format and location (e.g., `.nvim.lua` or `.nvim/config.lua` at project root) -- [ ] Implement loader to read nearest project config (git root fallback) -- [ ] Wire `intelephense.includePaths` from local config into LSP setup -- [ ] Document usage in repo README (example config) +- [x] 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` ## Phase 3.5 — LSP minimal defaults - [ ] Add `nvim-lspconfig` with minimal defaults (no over-configuration) @@ -178,3 +180,4 @@ 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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..83ee0b0 --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +# Neovim Rebuild — Decisions & Reference + +Authoritative notes for the Neovim migration. Use this alongside `MIGRATION_PLAN.md` and `neovim-migration-guide.md`. + +- Migration plan: MIGRATION_PLAN.md +- Guide and requirements: neovim-migration-guide.md + +## Decisions Log + +Record every decision here with a short rationale. Append new entries; do not rewrite history. + +- 2025-12-06: PHP LSP = `intelephense` (good PHP ecosystem support; integrates includePaths). +- 2025-12-06: Enable Markdown LSP = `marksman` (lightweight, good MD features). +- 2025-12-06: Use legacy `listchars` and `showbreak` values (preserve muscle memory). +- 2025-12-06: No direnv fallback for local config (keep setup simple and repo-driven). +- 2025-12-06: Project-local config = layered JSON `.nvim.json` + `.nvim.local.json` with `.nvimroot` as workspace boundary marker (multi-repo friendly). +- 2025-12-06: Switch to `folke/neoconf.nvim` for project-local configuration (supersedes custom layered JSON loader); use `.neoconf.json` at workspace root. +- 2025-12-06: Plugin approval policy — other plugins are allowed, but do not install any plugin not listed without explicit confirmation. + +## Project-Local Configuration (design) + +Context: Projects can contain multiple git repositories (e.g., WordPress site with theme + multiple plugins). We need a way to set per-project `intelephense.includePaths` and similar without globalizing settings. + +Options considered +- Layered JSON files (recommended): `.nvim.json` (committed) + `.nvim.local.json` (gitignored) + - Walk upward from current file; collect and merge configs until reaching a boundary marker or filesystem root. + - Boundary marker: `.nvimroot` to define a workspace that can encompass multiple repos. + - Merge order: top → bottom; nearest wins on conflicts; arrays replace by default unless we later add a merge strategy. + - Pros: safe (data-only), portable, reviewable in PRs. + - Cons: less dynamic than Lua. +- Layered Lua files: `.nvim.lua` + `.nvim.local.lua` + - Pros: maximum flexibility (computed paths). + - Cons: executes code from the repo; security gates required. +- Env/direnv: rejected (decision 2025-12-06). +- Central registry file in `~/.config/nvim/`: possible later for private overrides, but not primary. + +Chosen approach (confirmed) +- Use `folke/neoconf.nvim` with `.neoconf.json` at the workspace root (or project roots) to supply LSP/plugin settings. Multi-repo: keep a single `.neoconf.json` at the parent workspace folder and open Neovim from there (or use a rooter later if needed). + +Example `.neoconf.json` +``` +{ + "lspconfig": { + "intelephense": { + "settings": { + "intelephense": { + "environment": { + "includePaths": [ + "wp-content/themes/my-theme", + "wp-content/plugins/custom-plugin" + ] + } + } + } + } + } +} +``` +- Files recognized per directory level: + - `.nvim.json`: checked into VCS; shared per-project defaults. + - `.nvim.local.json`: gitignored; machine-specific overrides. +- Loader behavior: + 1. Start at the buffer’s directory; ascend toward root. + 2. Stop at directory containing `.nvimroot` (if found) or at filesystem root. + 3. At each level, if `.nvim.json` or `.nvim.local.json` exists, parse and stage for merge. + 4. Merge staged configs in ascending order; nearest directory applies last. +- Path resolution: + - Relative paths resolve against the topmost boundary (i.e., `.nvimroot` directory if present; otherwise the highest directory in which a config was found). This allows referencing sibling repos (e.g., theme and plugins) from a single top-level site folder. + +Example `.nvim.json` +``` +{ + "lsp": { + "php": { + "intelephense": { + "includePaths": [ + "wp-content/themes/my-theme", + "wp-content/plugins/custom-plugin", + "vendor/some-package/src" + ] + } + } + } +} +``` + +Intended integration +- A helper module `lua/local_config.lua` will expose: + - `load(start_dir) -> table` collecting and merging configs + - `get(path, default)` for reads, e.g., `get({"lsp","php","intelephense","includePaths"}, {})` +- LSP wiring (in Phase 3.5): + - Read includePaths via the helper and pass to `settings.intelephense.environment.includePaths` in `lspconfig.intelephense.setup{}`. + +Open items to confirm +- Confirm JSON as the format (vs Lua) for project-local config. +- Confirm `.nvimroot` as the workspace boundary marker name. +- Confirm array merge behavior (replace vs concatenate). Initial proposal: replace. + +## LSP Scope (initial) + +- Core servers: `lua_ls`, `tsserver`, `html`, `cssls`, `jsonls`, `bashls` +- PHP: `intelephense` (decision) +- Markdown: `marksman` (decision) +- Keep configuration minimal; defer language-specific tuning. + +## Text & Editing Settings + +- `spelllang = en_gb` +- `listchars` and `showbreak` will reuse legacy values. +- `completeopt = menu,menuone,noselect` for `nvim-cmp`. + +## Process Reminders + +- After any change or decision, update this README and MIGRATION_PLAN.md. +- Keep subphases small and verify each step in isolation. diff --git a/neovim-migration-guide.md b/neovim-migration-guide.md index bd5b1b8..5d062a5 100644 --- a/neovim-migration-guide.md +++ b/neovim-migration-guide.md @@ -140,7 +140,7 @@ When helping me implement these, please use modern Lua (`vim.api.nvim_*`, `vim.k * reintroduce old Vimscript workarounds * over-engineer or over-automate -* add plugins I did not ask for +* install any plugin not listed without explicit confirmation * suggest plugin-heavy “mega-setups” * attempt to recreate VS Code behaviour unless requested * produce large complex boilerplate unless requested