debug and problems
This commit is contained in:
Ali Can Zeybek
164
AGENTS.md
Normal file
164
AGENTS.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# AGENTS.md
|
||||
|
||||
This document is the operating guide for coding agents working in this Neovim
|
||||
configuration repository.
|
||||
|
||||
## Repository Snapshot
|
||||
|
||||
- Project type: personal Neovim config (Lua)
|
||||
- Entry point: `init.lua` -> `lua/core/*` -> `lua/plugins/*`
|
||||
- Plugin manager: `lazy.nvim`
|
||||
- No dedicated CI, test suite, formatter config, or lint config is committed
|
||||
- Primary language: Lua (Neovim runtime APIs)
|
||||
|
||||
## Directory Layout
|
||||
|
||||
- `init.lua`: bootstrap into core config
|
||||
- `lua/core/options.lua`: editor options and globals
|
||||
- `lua/core/keymaps.lua`: global and command keymaps
|
||||
- `lua/core/lazy.lua`: lazy.nvim bootstrap and setup
|
||||
- `lua/plugins/init.lua`: plugin spec list
|
||||
- `lua/plugins/config/*.lua`: per-plugin config modules
|
||||
- `lua/utils/*.lua`: utility helpers (for example `reload.lua`)
|
||||
|
||||
## Build / Lint / Test Commands
|
||||
|
||||
There is no Makefile/package manager script layer, so use direct commands.
|
||||
|
||||
### Environment checks
|
||||
|
||||
- Verify Neovim can start this config:
|
||||
- `nvim --headless -u /home/alican/.config/nvim/init.lua +qa`
|
||||
- Verify plugin bootstrap and lockfile resolution:
|
||||
- `nvim --headless -u /home/alican/.config/nvim/init.lua '+Lazy! sync' +qa`
|
||||
- Optional runtime health checks:
|
||||
- `nvim --headless -u /home/alican/.config/nvim/init.lua '+checkhealth' +qa`
|
||||
|
||||
### Formatting
|
||||
|
||||
- Preferred formatter for Lua: `stylua`
|
||||
- Format whole repo:
|
||||
- `stylua /home/alican/.config/nvim`
|
||||
- Format a single file:
|
||||
- `stylua /home/alican/.config/nvim/lua/plugins/init.lua`
|
||||
|
||||
If `stylua` is not installed, do not mass-reformat; preserve existing style in
|
||||
touched regions only.
|
||||
|
||||
### Linting
|
||||
|
||||
- No lint config is committed (`.luacheckrc` not found).
|
||||
- If `luacheck` is available, run ad hoc:
|
||||
- `luacheck /home/alican/.config/nvim/lua`
|
||||
- Treat lint as advisory unless the repository later adds pinned lint rules.
|
||||
|
||||
### Testing
|
||||
|
||||
- No test framework is currently configured in-repo.
|
||||
- Use headless startup as the minimum smoke test:
|
||||
- `nvim --headless -u /home/alican/.config/nvim/init.lua +qa`
|
||||
|
||||
### Running a single test (important)
|
||||
|
||||
There are no existing unit/integration test files, so there is no real
|
||||
single-test command today.
|
||||
|
||||
If you add Plenary-based tests, use this pattern for a single test file:
|
||||
|
||||
- `nvim --headless -u /home/alican/.config/nvim/init.lua -c "PlenaryBustedFile tests/<name>_spec.lua" -c qa`
|
||||
|
||||
If you add a plain Lua test runner later, document exact single-test invocations
|
||||
here and keep this section updated.
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
Follow local conventions observed in current files first, then these rules.
|
||||
|
||||
### Imports and module structure
|
||||
|
||||
- Use `require("...")` with explicit module paths.
|
||||
- Keep imports at top of file unless lazy-loading is intentional.
|
||||
- Prefer locals for required modules (example: `local cmp = require("cmp")`).
|
||||
- Return module tables (`local M = {}; ...; return M`) for utility modules.
|
||||
- Plugin config modules should avoid side effects outside setup behavior.
|
||||
|
||||
### Formatting and layout
|
||||
|
||||
- Preserve existing indentation style per file (repo currently mixes tabs/spaces).
|
||||
- Keep lines reasonably short (existing config uses `colorcolumn = "80"`).
|
||||
- Use trailing commas in multiline Lua tables.
|
||||
- Keep one logical statement per line.
|
||||
- Group related options/settings in contiguous blocks.
|
||||
- Avoid large unrelated reformatting in feature/fix commits.
|
||||
|
||||
### Types and annotations
|
||||
|
||||
- Lua is dynamically typed here; no strict type checker is configured.
|
||||
- Keep useful EmmyLua annotations when present (for example `---@type ...`).
|
||||
- Add annotations only when they improve editor/LSP inference.
|
||||
- Do not add noisy type comments for obvious locals.
|
||||
|
||||
### Naming conventions
|
||||
|
||||
- Module/file names: lowercase, path-based (`core.options`, `plugins.config.lsp`).
|
||||
- Local variables: `snake_case`.
|
||||
- Exported module tables: `M`.
|
||||
- User commands: `PascalCase` where already used (`ReloadConfig`).
|
||||
- Avoid introducing new global functions/variables.
|
||||
- Exception: if global is required by Vim command callbacks, prefix carefully and
|
||||
document intent.
|
||||
|
||||
### Neovim API usage
|
||||
|
||||
- Prefer modern APIs:
|
||||
- `vim.keymap.set` over `vim.api.nvim_set_keymap`
|
||||
- `vim.api.nvim_create_user_command` for user commands
|
||||
- Use buffer-local mappings/options when behavior is buffer-scoped.
|
||||
- Keep plugin setup isolated in `lua/plugins/config/<plugin>.lua` when practical.
|
||||
- Keep core bootstrap files (`core/*`) minimal and composable.
|
||||
|
||||
### Error handling and resilience
|
||||
|
||||
- Fail softly for optional dependencies when reasonable (`pcall(require, ...)`).
|
||||
- Avoid crashing startup for non-critical plugin behavior.
|
||||
- Use `vim.notify(..., vim.log.levels.<LEVEL>)` for actionable runtime feedback.
|
||||
- For external commands in Lua, check return status if failure is meaningful.
|
||||
|
||||
### Plugin and dependency changes
|
||||
|
||||
- Add/modify plugin specs only in `lua/plugins/init.lua` unless refactoring.
|
||||
- Keep plugin options in dedicated config modules when they grow beyond trivial.
|
||||
- For plugins with build hooks (example: markdown preview), do not assume Node/npm
|
||||
is available in all environments; mention prerequisites in PR notes.
|
||||
- Preserve lockfile intent (`lazy-lock.json`) when updating plugin versions.
|
||||
|
||||
### Commit hygiene for agents
|
||||
|
||||
- Make focused changes with minimal scope.
|
||||
- Do not fix unrelated style issues opportunistically.
|
||||
- Include validation notes in your final response (what you ran, what you could
|
||||
not run).
|
||||
- If commands are unavailable locally, state that clearly and provide exact
|
||||
follow-up commands.
|
||||
|
||||
## Cursor / Copilot Rules
|
||||
|
||||
Checked paths:
|
||||
|
||||
- `.cursorrules`
|
||||
- `.cursor/rules/`
|
||||
- `.github/copilot-instructions.md`
|
||||
|
||||
Current status: no Cursor or Copilot instruction files were found in this
|
||||
repository.
|
||||
|
||||
If these files are added later, agents must treat them as higher-priority
|
||||
repository policy and this document should be updated to summarize them.
|
||||
|
||||
## Agent Workflow Checklist
|
||||
|
||||
- Read nearby files before editing; match local patterns.
|
||||
- Keep edits minimal and reversible.
|
||||
- Run at least one headless Neovim smoke check after non-trivial changes.
|
||||
- For plugin changes, run `'+Lazy! sync'` headless when possible.
|
||||
- Update this file when tooling, test framework, or style policy changes.
|
||||
Reference in New Issue
Block a user