From bbe744339df2a1ab6f900df7b541f9561dcb2fbd Mon Sep 17 00:00:00 2001 From: ray Date: Mon, 8 Dec 2025 00:35:08 +0000 Subject: [PATCH] add phase for colorscheme migration Paper Tonic colorscheme and custom highlights - Port Paper Tonic colorscheme as a local plugin. - Add custom TreeSitter captures for CSS and HTML. - Verify and extend highlights for plugins and captures. - Retire legacy highlights and validate performance. --- AGENTS.md | 91 ++++++++++++++++++++---- MIGRATION_PLAN.md | 57 ++++++++++++--- after/queries/css/highlights.scm | 18 +++++ after/queries/html/highlights.scm | 17 +++++ legacy/after/queries/ecma/highlights.scm | 0 5 files changed, 162 insertions(+), 21 deletions(-) create mode 100644 after/queries/css/highlights.scm create mode 100644 after/queries/html/highlights.scm delete mode 100644 legacy/after/queries/ecma/highlights.scm diff --git a/AGENTS.md b/AGENTS.md index 2364acb..36ec831 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,16 +8,20 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu - Modern Lua-first config; avoid Vimscript unless explicitly requested. - Keep it minimal, fast, and maintainable. - Base plugin management on `lazy.nvim` with modular plugin specs. -- Support tab-per-context workflow with Neo-tree per tab, Telescope navigation, LSP, Treesitter, Copilot, and sane UX defaults. +- Support Telescope navigation, netrw for file browsing/preview, Oil.nvim for file operations, LSP, Treesitter, Copilot, and sane UX defaults. +- Native project-local configuration via `exrc` + `secure` (no external config plugins). ## Do Not Reintroduce - Custom Vimscript tabline/statusline, foldtext, UI hacks. - Legacy autocommands toggling cursorline/column per window. - CoC or CoC-specific config. -- netrw settings (Neo-tree will be used). +- Neo-tree (skipped in favor of netrw for navigation). - Providers for ruby/perl/node (disable unless required by a plugin). - Auto-reload vimrc-on-write templates. - `cursorcolumn` and old folding logic not related to UFO. +- neoconf plugin (incompatible with Neovim 0.11+, use native exrc instead). +- Motion plugins like leap.nvim or flash.nvim (not needed). +- Markdown rendering plugins (skipped entirely). ## Repository Structure (target) ``` @@ -39,7 +43,26 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu ├── oil.lua ├── ufo.lua ├── gitsigns.lua - └── none-ls.lua + ├── none-ls.lua + ├── nvim-lint.lua + ├── mason.lua + ├── mason-lspconfig.lua + ├── mason-tool-installer.lua + ├── comment.lua + ├── surround.lua + ├── autopairs.lua + └── indent-blankline.lua +├── after/ +│ ├── ftplugin/ +│ │ └── php.lua -- PHP-specific settings (includeexpr for gf) +│ └── queries/ -- Custom Treesitter queries +│ ├── css/ +│ │ └── highlights.scm +│ └── html/ +│ └── highlights.scm +├── templates/ +│ └── template.sh -- Shell script template +└── legacy/ -- Archived Vimscript config (reference only) ``` ## Coding Conventions @@ -55,24 +78,26 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu - Each plugin lives in `lua/plugins/.lua` and returns a spec table. - Use `opts = {}` for default options and `config = function(_, opts) ... end` for setup. - 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. +- Rejected: `folke/neoconf.nvim` (incompatible with Neovim 0.11+ vim.lsp.config API). ## Required Plugin Categories - Core: `nvim-lspconfig`, `nvim-cmp`, `cmp-nvim-lsp`, `cmp-buffer`, `cmp-path`, `LuaSnip`. -- Navigation: `neo-tree.nvim`, `telescope.nvim` (+ optional `telescope-fzf-native.nvim`). +- Navigation: `telescope.nvim` + `telescope-fzf-native.nvim`, `oil.nvim`. - Treesitter: `nvim-treesitter`, `nvim-treesitter-textobjects`, `nvim-ts-autotag`. -- UX/Editing: `Comment.nvim`, `surround.nvim`, `nvim-autopairs`, `indent-blankline.nvim`, `leap.nvim` or `flash.nvim`, `nvim-ufo`, `undotree` (optional). +- UX/Editing: `Comment.nvim`, `nvim-surround`, `nvim-autopairs`, `indent-blankline.nvim`, `nvim-ufo`, `undotree`. - Git: `gitsigns.nvim`. -- Markdown: `render-markdown.nvim`. - Copilot: `copilot.lua`, `copilot-cmp`. -- Formatting: `none-ls.nvim`. +- Formatting/Linting: `none-ls.nvim`, `nvim-lint`. +- LSP Management: `mason.nvim`, `mason-lspconfig.nvim`, `mason-tool-installer.nvim`. ## Workflow Requirements to Preserve -- Tab-per-context: each tab has its own Neo-tree root. -- Provide keymaps for: Neo-tree floating, Neo-tree sidebar toggle, and file preview. Previews should not pollute buffer list. -- Keep splits inside tabs. -- Use Telescope and LSP for navigation. +- Netrw for visual context and project structure browsing (tree view, preview splits). +- Telescope for fuzzy finding (files, grep, buffers, LSP symbols). +- Oil.nvim for file manipulation (handles buffer sync on rename/move/delete). +- LSP for navigation (gd, gr, K, etc.). - Heavy HTML/PHP/JS/Markdown usage (WordPress plugin dev) — prioritize these languages in LSP/Treesitter. +- Format-on-save with toggle capability. +- Project-local configuration via `.nvim.lua` files. ## Behaviours to Keep (modernized) - Abbreviations: `adn→and`, `waht→what`, `tehn→then`, `functin→function`, `positin→position`. @@ -80,6 +105,19 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu - Whitespace highlighting (use modern alternatives, e.g., `listchars`, plugins if needed). - Persistent folds (prefer `nvim-ufo`). - Spell & text: `spelllang=en_gb`, custom `listchars`, `showbreak`. +- Keyword characters: `iskeyword+=$` (for PHP/shell variables), `iskeyword+=-` (for CSS/HTML/config files). + +## Current Status (Phase 10 Complete) +- ✅ Phase 1-2: Archive legacy, bootstrap lazy.nvim +- ✅ Phase 3: Core editing & LSP (native exrc + vim.lsp.config migration complete) +- ✅ Phase 4: Navigation (Telescope, netrw, Oil.nvim) +- ✅ Phase 5: Treesitter (parsers, textobjects, autotag) +- ✅ Phase 6: UX/Editing (Comment, surround, autopairs, indent guides, UFO, undotree) +- ✅ Phase 7: Git integration (Gitsigns) +- ✅ Phase 8: Copilot integration (copilot.lua + copilot-cmp) +- ✅ Phase 9: Formatting & Linting (none-ls, nvim-lint, Mason tool installer) +- ✅ Phase 10: Migrate kept behaviors (abbreviations, templates, custom Treesitter queries) +- ⏸️ Phase 11: Cleanup & validation (pending) ## Migration Notes - Do not edit legacy Vimscript files except to extract settings to Lua. Keep them intact until migration completes. @@ -90,9 +128,36 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu ## Validation - Ensure Neovim starts without errors and with minimal startup time. -- Verify tab workflow, Neo-tree behaviour, Telescope, LSP basics, and completion. +- Verify Telescope navigation, netrw browsing, Oil.nvim file operations, LSP basics, and completion. - Keep plugin count tight; remove anything unused. +## Key Decisions & Architecture + +### LSP Configuration +- **Modern API (Neovim 0.11+)**: Uses `vim.lsp.config()` + `vim.lsp.enable()`, NOT `require('lspconfig')[server].setup()` +- **Project-local config**: Native `exrc` + `secure` (no neoconf - incompatible with 0.11+) +- **Config format**: `.nvim.lua` files return `{ lsp = { [server_name] = { settings = {...} } } }` +- **Security**: `secure` mode prompts user to trust `.nvim.lua` files (one-time per file hash) +- **Settings loading**: `on_new_config` hook loads from actual `root_dir` (not cwd) +- **PHP**: intelephense with `single_file_support = false`, uses `environment.includePaths` for external libs + +### Navigation Strategy +- **netrw**: Visual context, tree view, preview splits (horizontal 50/50 below) +- **Telescope**: Fuzzy finding (files, grep, buffers, LSP symbols) +- **Oil.nvim**: File manipulation (handles buffer sync on rename/move/delete) +- **PHP gf enhancement**: Custom `includeexpr` in `after/ftplugin/php.lua` for WordPress/PHP patterns + +### Formatting & Linting +- **Formatters**: prettier, phpcbf, stylua, black (project-local → Mason → global) +- **Linters**: eslint_d, phpcs, markdownlint, ruff (via nvim-lint) +- **Format-on-save**: Enabled by default, toggle with `lt` +- **Philosophy**: Formatters are source of truth; Neovim settings match formatter rules per filetype + +### Treesitter +- **Parsers**: lua, vim, vimdoc, php, html, javascript, typescript, tsx, css, scss, json, markdown, bash, regex +- **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag +- **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm` + ## 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. diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 3ab9485..d0f2acc 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -334,25 +334,66 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date. - [x] Persistent folds (via UFO) -- no need, this is no longer required. - [x] Note: UFO handles folding; no explicit persistence mechanism needed -## Phase 11 — Cleanup & Validation +## Phase 11 — Colorscheme Integration ## Phase 11.1 — Confirm scope and priorities - [ ] Confirm scope and priorities for this phase +- [ ] Decision: Port Paper Tonic colorscheme from `~/projects/nvim-paper-tonic` +- [ ] Decision: Install as local plugin via lazy.nvim (use `dir = '~/projects/nvim-paper-tonic'`) +- [ ] Decision: Test first, then extend with missing highlights as needed +- [ ] Custom TreeSitter captures to verify/define: `@CssClassName`, `@CssIdentifier`, `@DataAttribute`, `@DataAttributeValue`, `@cssPseudoClass`, `@cssNestingSelector`, etc. -## Phase 11.2 — Retire legacy files +## Phase 11.2 — Install Paper Tonic colorscheme +- [ ] Create `lua/plugins/colorscheme.lua` with Paper Tonic as local plugin +- [ ] Set `lazy = false` and `priority = 1000` to load first +- [ ] Apply colorscheme in config function + +## Phase 11.3 — Verify custom TreeSitter highlights +- [ ] Open HTML/CSS files and verify custom captures have colors +- [ ] Check if `@CssClassName` (HTML class attributes) matches CSS class selector colors +- [ ] Check if `@CssIdentifier` (HTML id attributes) matches CSS id selector colors +- [ ] Check if `@DataAttribute` and `@DataAttributeValue` are distinct +- [ ] Check CSS-specific captures: `@cssPseudoClass`, `@cssNestingSelector`, `@CssUniversalSelector`, etc. + +## Phase 11.4 — Verify plugin highlights +- [ ] Telescope UI (borders, selection, prompts) +- [ ] Gitsigns (add, change, delete signs in gutter) +- [ ] nvim-cmp (completion menu, selected item, kind icons) +- [ ] LSP diagnostics (ERROR, WARN, HINT, INFO signs and virtual text) +- [ ] Oil.nvim (if distinctive colors needed) + +## Phase 11.5 — Add missing highlights (if needed) +- [ ] Create `lua/colorscheme-overrides.lua` if custom highlights needed +- [ ] Define highlights for custom TreeSitter captures not in colorscheme +- [ ] Define highlights for plugins not covered by colorscheme +- [ ] Load overrides after colorscheme applies (use autocmd or lazy.nvim config) + +## Phase 12 — Cleanup & Validation + +## Phase 12.1 — Confirm scope and priorities +- [ ] Confirm scope and priorities for this phase + +## Phase 12.2 — Retire legacy files - [ ] Retire legacy Vimscript files (keep for reference until verified) -## Phase 11.3 — Startup performance +## Phase 12.3 — Startup performance - [ ] Validate startup performance (no errors, fast launch) -## Phase 11.4 — Tab workflow validation -- [ ] Validate tab-per-context workflow with Neo-tree (if used) - -## Phase 11.5 — Navigation validation +## Phase 12.4 — Navigation validation - [ ] Validate Telescope navigation + LSP jumps +- [ ] Validate netrw browsing and preview splits +- [ ] Validate Oil.nvim file operations -## Phase 11.6 — Language tooling validation +## Phase 12.5 — Language tooling validation - [ ] Validate HTML/PHP/JS/Markdown tooling +- [ ] Verify LSP (gd, gr, K, diagnostics) +- [ ] Verify formatting (prettier, phpcbf, stylua) +- [ ] Verify linting (eslint_d, phpcs, markdownlint) + +## Phase 12.6 — Final polish +- [ ] Review all keymaps and ensure they're documented +- [ ] Update README.md with final architecture and usage +- [ ] Clean up any remaining debug code or temporary comments --- diff --git a/after/queries/css/highlights.scm b/after/queries/css/highlights.scm new file mode 100644 index 0000000..7fa2000 --- /dev/null +++ b/after/queries/css/highlights.scm @@ -0,0 +1,18 @@ +(id_selector (id_name) @CssIdentifier) +(id_selector (id_name)) @CssIdSelector +(tag_name) @HtmlTagName + +(class_selector (class_name) @CssClassName) +(selectors (pseudo_class_selector (class_name) @cssPseudoClass)) +(nesting_selector) @cssNestingSelector + +; need to find out how to make this more specific? +(universal_selector) @CssUniversalSelector + +((property_name) (_)) @CssProp + +(unit) @CssUnit + +(declaration (property_name) (_) @CssPropertyValue) + +(media_statement (feature_query (feature_name) @cssMediaFeatureName (_ (unit) @cssMediaQueryValueUnit) @cssMediaQueryValue) @cssMediaQuery) diff --git a/after/queries/html/highlights.scm b/after/queries/html/highlights.scm new file mode 100644 index 0000000..2b752d4 --- /dev/null +++ b/after/queries/html/highlights.scm @@ -0,0 +1,17 @@ +(start_tag + (attribute + (attribute_name) @ClassNameAttribute (#eq? @ClassNameAttribute "class") + (quoted_attribute_value + (attribute_value) @CssClassName ))) + +(start_tag + (attribute + (attribute_name) @IdAttribute (#eq? @IdAttribute "id") + (quoted_attribute_value + (attribute_value) @CssIdentifier ))) + +(start_tag + (attribute + (attribute_name) @DataAttribute (#match? @DataAttribute "^data-") + (quoted_attribute_value + (attribute_value) @DataAttributeValue ))) diff --git a/legacy/after/queries/ecma/highlights.scm b/legacy/after/queries/ecma/highlights.scm deleted file mode 100644 index e69de29..0000000