update
This commit is contained in:
parent
53b6b9e7d8
commit
a0049b8e06
13
AGENTS.md
13
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/<name>.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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue