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: Use mason.nvim + mason-lspconfig.nvim to install/manage LSP servers; keep custom lspconfig setup; include .neoconf.json in root detection.
  • For PHP validation inside this repo: we require .neoconf.json to attach intelephense to avoid the repo’s .git being chosen as the LSP 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.