Skip to content

Commit d273f0d

Browse files
ellisonleaoellisonleao
authored
Merge pull request #413 from ellisonleao/copilot/fix-9c47ac37-62ad-45b8-83a5-f56bee3740e2
Add comprehensive .github/copilot-instructions.md for coding agent onboarding
2 parents 12c2624 + d625862 commit d273f0d

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Copilot Instructions for gruvbox.nvim
2+
3+
## Repository Overview
4+
5+
**gruvbox.nvim** is a Neovim colorscheme plugin that ports the popular gruvbox community theme to Lua with treesitter and semantic highlighting support. This is a single-module Lua plugin targeting Neovim 0.8.0+ with extensive customization capabilities.
6+
7+
**Key Stats:**
8+
- Primary language: Lua (1,343 lines in main module)
9+
- Target runtime: Neovim 0.8.0+
10+
- License: MIT
11+
- Architecture: Single module with configuration-driven design
12+
13+
## Project Structure
14+
15+
### Core Files
16+
- `lua/gruvbox.lua` - Main implementation (1,343 lines) containing all colorscheme logic
17+
- `colors/gruvbox.lua` - Simple loader that calls `require("gruvbox").load()`
18+
- `README.md` - User documentation with installation and configuration examples
19+
- `doc/gruvbox.nvim.txt` - Auto-generated Vim help documentation
20+
21+
### Testing Infrastructure
22+
- `tests/gruvbox/gruvbox_spec.lua` - Test suite (189 lines) using plenary.nvim
23+
- `tests/minimal_init.lua` - Test setup that auto-downloads plenary.nvim if missing
24+
- `Makefile` - Contains `test` target for running tests
25+
26+
### Configuration
27+
- `stylua.toml` - Code formatting configuration (120 char width, 2-space indent)
28+
- `.github/workflows/` - CI/CD automation (test, docs, luarocks publishing)
29+
30+
## Build and Validation Commands
31+
32+
### Prerequisites
33+
- **Neovim 0.8.0+** is REQUIRED - tests and functionality will fail on older versions
34+
- **stylua** for code formatting (auto-installed in CI)
35+
- **plenary.nvim** for testing (auto-downloaded by test setup)
36+
37+
### Validated Command Sequences
38+
39+
#### Testing (Always works - tested)
40+
```bash
41+
make test
42+
```
43+
- Downloads plenary.nvim to `/tmp/plenary.nvim` if not present
44+
- Runs all tests using Neovim headless mode
45+
- **Expected result:** 9 tests pass, 0 failures
46+
- **Time required:** ~5-10 seconds
47+
- **Dependencies:** Requires `nvim` in PATH
48+
49+
#### Code Formatting (Always works - tested)
50+
```bash
51+
stylua --check lua
52+
```
53+
- Validates Lua code formatting against stylua.toml config
54+
- **Expected result:** No output means code is properly formatted
55+
- **To fix formatting:** `stylua lua` (without --check flag)
56+
57+
#### Manual Loading Test
58+
```bash
59+
nvim --headless -c "set rtp+=$PWD" -c "lua require('gruvbox').setup()" -c "colorscheme gruvbox" -c "echo 'Colorscheme loaded successfully'" -c "q"
60+
```
61+
- Quick test to ensure colorscheme loads without errors
62+
- Should print "Colorscheme loaded successfully" and exit cleanly
63+
- **Note:** Requires setting runtime path to current directory
64+
65+
### CI/CD Pipeline
66+
67+
**GitHub Actions workflows (all validated):**
68+
69+
1. **test.yml** - Runs on push/PR
70+
- Tests on Neovim stable and nightly
71+
- Runs stylua formatting check
72+
- Runs full test suite
73+
74+
2. **docs.yml** - Runs on main branch push
75+
- Auto-generates `doc/gruvbox.nvim.txt` from README.md using panvimdoc
76+
- Commits changes automatically
77+
78+
3. **luarocks.yml** - Runs on version tags
79+
- Publishes releases to LuaRocks
80+
81+
## Architecture and Key Concepts
82+
83+
### Main Module Structure (`lua/gruvbox.lua`)
84+
- **Gruvbox table**: Main module with `config`, `palette`, `setup()`, and `load()` methods
85+
- **Configuration system**: Deep-mergeable config with extensive defaults
86+
- **Color palette**: Comprehensive gruvbox color definitions with override support
87+
- **Highlight groups**: Extensive definitions covering core Vim, treesitter, LSP, and plugin integrations
88+
89+
### Critical Implementation Details
90+
- `setup()` must be called BEFORE `colorscheme gruvbox` command
91+
- Configuration is deep-copied and merged to prevent mutation
92+
- Multiple `setup()` calls are independent (previous state is not preserved)
93+
- Supports both light and dark backgrounds with contrast levels (hard/soft/normal)
94+
95+
### Plugin Integrations
96+
The colorscheme includes highlights for 40+ plugins including:
97+
- Treesitter and LSP semantic tokens
98+
- Popular plugins: telescope, nvim-tree, gitsigns, lualine, etc.
99+
- Terminal colors support for integrated terminal
100+
101+
## Common Development Workflows
102+
103+
### Making Changes to Colors
104+
1. Edit `lua/gruvbox.lua` in the palette section or highlight groups
105+
2. Test with `nvim -c "lua require('gruvbox').setup()" -c "colorscheme gruvbox"`
106+
3. Run `make test` to ensure no regressions
107+
4. Run `stylua lua` to format code
108+
109+
### Adding New Plugin Support
110+
1. Add highlight group definitions in the `groups` table within `get_groups()` function
111+
2. Follow existing patterns for naming (use plugin name prefix)
112+
3. Test with the target plugin installed
113+
4. Add tests in `tests/gruvbox/gruvbox_spec.lua` if needed
114+
115+
### Configuration Changes
116+
1. Update `default_config` table for new options
117+
2. Update type annotations (`@class GruvboxConfig`)
118+
3. Handle new options in `get_groups()` function
119+
4. Update README.md with examples
120+
5. Tests are auto-updated for documentation
121+
122+
## Error Patterns and Solutions
123+
124+
### Common Issues
125+
- **"gruvbox.nvim: you must use neovim 0.8 or higher"**: Version check failure - use newer Neovim
126+
- **Test failures**: Usually indicate breaking changes to configuration or highlight logic
127+
- **Formatting failures**: Run `stylua lua` to fix formatting issues
128+
129+
### Debugging Workflow
130+
1. Use `:hi` command in Neovim to inspect highlight groups
131+
2. Use `:lua print(vim.inspect(require('gruvbox').config))` to debug configuration
132+
3. Test color changes with `:lua require('gruvbox').load()` for quick iteration
133+
134+
## Files and Dependencies Not Obvious from Structure
135+
136+
### Hidden Dependencies
137+
- Tests depend on `plenary.nvim` but auto-download it
138+
- Documentation generation depends on `panvimdoc` action
139+
- LuaRocks publishing requires `LUAROCKS_API_KEY` secret
140+
141+
### Generated Files
142+
- `doc/gruvbox.nvim.txt` - Auto-generated, don't edit manually
143+
- Documentation updates trigger on main branch pushes
144+
145+
## Repository Root Files
146+
```
147+
.
148+
├── .github/ # CI/CD workflows and issue templates
149+
├── .gitignore # Excludes build artifacts and test dependencies
150+
├── LICENSE # MIT license
151+
├── Makefile # Test automation
152+
├── README.md # User documentation and examples
153+
├── colors/ # Vim colorscheme loader
154+
├── doc/ # Auto-generated vim help documentation
155+
├── lua/ # Main Lua implementation
156+
├── stylua.toml # Code formatting configuration
157+
└── tests/ # Test suite with plenary.nvim
158+
```
159+
160+
## Trust These Instructions
161+
162+
These instructions are comprehensive and tested. Only search for additional information if you encounter errors or if specific requirements aren't covered above. The command sequences have been validated and the architectural information is current as of the latest codebase analysis.
163+
164+
**Always run `make test` before making changes to understand the current state, and run it again after changes to ensure no regressions.**

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Build artifacts and dependencies
2+
nvim-linux64/
3+
nvim-linux64.tar.gz
4+
nvim.appimage
5+
stylua
6+
stylua.zip
7+
8+
# Test dependencies
9+
vendor/

0 commit comments

Comments
 (0)