kentchiu aider.nvim .cursorrules file for Lua (stars: 1)

# Neovim Plugin Lua AI Coding Agent Guidelines

You are an expert in Neovim plugins programming, with deep knowledge of its unique features and common use cases in neovim plugin Development.


## Key Principles
- Write idiomatic Lua code optimized for Neovim's runtime and API ecosystem.
- Leverage the latest Neovim APIs (`vim.api`, `vim.fn`, `vim.treesitter`, `vim.loop`, etc.).
- Use `Luals Annotations` for comprehensive API documentation and type checking.
- Ensure code is modular, maintainable, and easy to extend.
- Optimize for performance while maintaining readability and clarity.
- Neovim version is 0.10+, AVOID USE DRPRECATED API. DONT BE LAZY

---

## Lua-Specific Guidelines for Neovim Plugins

### Naming Conventions
- Use `snake_case` for variables and functions.
- Use `PascalCase` for modules or public classes.
- Use `UPPERCASE` for constants.
- Prefix private functions or variables with `_`.
- Use descriptive and purpose-revealing names.

### Code Organization
- Group related functionality into modules.
- Use `require()` for dependencies, ensuring proper file modularity.
- Keep functions local to a module unless explicitly exported.
- Separate plugin logic, configuration, and mappings into distinct files or namespaces.
- Use clear comments and `Luals Annotations` for all exported APIs.

---

## Neovim-Specific Best Practices

### API Usage
- Prefer `vim.api.nvim_*` over deprecated Vimscript commands.
- Use `vim.keymap.set()` for defining keymaps instead of `vim.api.nvim_set_keymap`.
- Manage user options with `vim.opt` and buffer-specific settings with `vim.bo` or `vim.wo`.
- Use `vim.notify()` for user notifications instead of `print()`.

### Asynchronous Operations
- Use `vim.loop` for performance-critical async tasks.
- Schedule UI updates with `vim.schedule_wrap()` or `vim.defer_fn()`.
- Avoid blocking the main thread—favor async functions when dealing with I/O or long computations.

### Luals Annotations
- Use `---@type` for type definitions.
- Document APIs with `---@param` and `---@return` for improved developer experience.
- Add `---@class` for structured objects or configurations.
- Example:
  ```lua
  --- Resize the current window.
  ---@param width number The desired width of the window.
  ---@return boolean success True if resizing was successful.
  local function resize_window(width)
      vim.api.nvim_win_set_width(0, width)
      return true
  end
  ```

---

## Error Handling
- Use `pcall` or `xpcall` for protected calls, especially when interacting with external commands.
- Provide meaningful error messages via `vim.notify`.
- Use `assert()` for preconditions and validate user input explicitly.


---


## Documentation
- Use `Luals Annotations` extensively to define types, parameters, and return values.
- Maintain `README.md` with clear setup instructions and usage examples.
- Use `help` files for in-editor documentation (`:help myplugin`).


---

## Common Patterns
- Use `require('myplugin.module')` for modular design.
- Define lazy-loaded autocommands and keymaps in `plugin/*.lua` files.
- Create extensible configurations:
  ```lua
  local M = {}
  M.config = {
      option1 = true,
      option2 = "default",
  }

  function M.setup(user_config)
      M.config = vim.tbl_deep_extend("force", M.config, user_config or {})
  end

  return M
  ```
## Deprecated API


Nvim                                                             *deprecated*

The items listed below are deprecated: they will be removed in the future.
They should not be used in new scripts, and old scripts should be updated.

==============================================================================
Deprecated features

------------------------------------------------------------------------------
DEPRECATED IN 0.11					*deprecated-0.11*

API
• nvim_subscribe()	Plugins must maintain their own "multicast" channels list.
• nvim_unsubscribe()	Plugins must maintain their own "multicast" channels list.

DIAGNOSTICS
• *vim.diagnostic.goto_next()*	Use |vim.diagnostic.jump()| with `{count=1, float=true}` instead.
• *vim.diagnostic.goto_prev()*	Use |vim.diagnostic.jump()| with `{count=-1, float=true}` instead.
• *vim.diagnostic.get_next_pos()* Use the "lnum" and "col" fields from the
				return value of |vim.diagnostic.get_next()| instead.
• *vim.diagnostic.get_prev_pos()* Use the "lnum" and "col" fields from the
				return value of |vim.diagnostic.get_prev()| instead.
• The "win_id" parameter used by various functions is deprecated in favor of
  "winid" |winid|
• |vim.diagnostic.JumpOpts| renamed its "cursor_position" field to "pos".

HIGHLIGHTS
• *TermCursorNC*	Unfocused |terminal| windows do not have a cursor.

LSP
• *vim.lsp.util.jump_to_location*	Use |vim.lsp.util.show_document()| with
					`{focus=true}` instead.
• *vim.lsp.buf.execute_command*		Use |Client:exec_cmd()| instead.
• *vim.lsp.buf.completion*		Use |vim.lsp.completion.trigger()| instead.
• vim.lsp.buf_request_all		The `error` key has been renamed to `err` inside
					the result parameter of the handler.
• *vim.lsp.with()*			Pass configuration to equivalent
					functions in `vim.lsp.buf.*`.
• |vim.lsp.handlers| Does not support client-to-server response handlers. Only
  supports server-to-client requests/notification handlers.
• *vim.lsp.handlers.signature_help()*	Use |vim.lsp.buf.signature_help()| instead.
• `client.request()`			Use |Client:request()| instead.
• `client.request_sync()`		Use |Client:request_sync()| instead.
• `client.notify()`			Use |Client:notify()| instead.
• `client.cancel_request()`		Use |Client:cancel_request()| instead.
• `client.stop()`			Use |Client:stop()| instead.
• `client.is_stopped()`			Use |Client:is_stopped()| instead.
• `client.supports_method()`		Use |Client:supports_method()| instead.
• `client.on_attach()`			Use |Client:on_attach()| instead.
• `vim.lsp.start_client()`		Use |vim.lsp.start()| instead.

LUA
• vim.region()		Use |getregionpos()| instead.
• *vim.highlight*	Renamed to |vim.hl|.
• vim.validate(opts: table) Use form 1. See |vim.validate()|.

TREESITTER
• *TSNode:child_containing_descendant()* Use |TSNode:child_with_descendant()|
  instead; it is identical except that it can return the descendant itself.

VIMSCRIPT
• *termopen()* Use |jobstart() with `{term: v:true}`.

------------------------------------------------------------------------------
DEPRECATED IN 0.10					*deprecated-0.10*

API
• *nvim_buf_get_option()*	Use |nvim_get_option_value()| instead.
• *nvim_buf_set_option()*	Use |nvim_set_option_value()| instead.
• *nvim_call_atomic()*		Use |nvim_exec_lua()| instead.
• *nvim_get_option()*		Use |nvim_get_option_value()| instead.
• *nvim_set_option()*		Use |nvim_set_option_value()| instead.
• *nvim_win_get_option()*	Use |nvim_get_option_value()| instead.
• *nvim_win_set_option()*	Use |nvim_set_option_value()| instead.

CHECKHEALTH
• *health#report_error* *vim.health.report_error()*	Use |vim.health.error()| instead.
• *health#report_info* *vim.health.report_info()*	Use |vim.health.info()| instead.
• *health#report_ok* *vim.health.report_ok()*		Use |vim.health.ok()| instead.
• *health#report_start* *vim.health.report_start()*	Use |vim.health.start()| instead.
• *health#report_warn* *vim.health.report_warn()*	Use |vim.health.warn()| instead.

DIAGNOSTICS
• Configuring |diagnostic-signs| using |:sign-define| or |sign_define()|. Use
  the "signs" key of |vim.diagnostic.config()| instead.
• vim.diagnostic functions:
  • *vim.diagnostic.disable()*		Use |vim.diagnostic.enable()|
  • *vim.diagnostic.is_disabled()*	Use |vim.diagnostic.is_enabled()|
  • Legacy signature: `vim.diagnostic.enable(buf:number, namespace:number)`

LSP
• *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| instead.
• *vim.lsp.get_active_clients()*		Use |vim.lsp.get_clients()| instead.
• *vim.lsp.for_each_buffer_client()*		Use |vim.lsp.get_clients()| instead.
• *vim.lsp.util.trim_empty_lines()*		Use |vim.split()| with `trimempty` instead.
• *vim.lsp.util.try_trim_markdown_code_blocks()*
• *vim.lsp.util.set_lines()*
• *vim.lsp.util.extract_completion_items()*
• *vim.lsp.util.parse_snippet()*
• *vim.lsp.util.text_document_completion_list_to_complete_items()*
• *vim.lsp.util.lookup_section()*		Use |vim.tbl_get()| instead: >
						local keys = vim.split(section, '.', { plain = true })
						local  vim.tbl_get(table, unpack(keys))

LUA
• *vim.loop*				Use |vim.uv| instead.
• *vim.tbl_add_reverse_lookup()*
• *vim.tbl_flatten()*			Use |Iter:flatten()| instead.
• *vim.tbl_islist()*			Use |vim.islist()| instead.

OPTIONS
• The "term_background" UI option |ui-ext-options| is deprecated and no longer
  populated. Background color detection is now performed in Lua by the Nvim
  core, not the TUI.

TREESITTER
• *LanguageTree:for_each_child()*	Use |LanguageTree:children()| (non-recursive) instead.


------------------------------------------------------------------------------
DEPRECATED IN 0.9					*deprecated-0.9*

API
• *nvim_get_hl_by_name()*		Use |nvim_get_hl()| instead.
• *nvim_get_hl_by_id()*			Use |nvim_get_hl()| instead.

TREESITTER
• *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()| instead.
• *vim.treesitter.get_node_at_pos()*		Use |vim.treesitter.get_node()| instead.
• *vim.treesitter.get_node_at_cursor()*		Use |vim.treesitter.get_node()|
						and |TSNode:type()| instead.
• The following top level Treesitter functions have been moved:
  • *vim.treesitter.inspect_language()*    -> |vim.treesitter.language.inspect()|
  • *vim.treesitter.get_query_files()*     -> |vim.treesitter.query.get_files()|
  • *vim.treesitter.set_query()*           -> |vim.treesitter.query.set()|
  • *vim.treesitter.query.set_query()*     -> |vim.treesitter.query.set()|
  • *vim.treesitter.get_query()*           -> |vim.treesitter.query.get()|
  • *vim.treesitter.query.get_query()*     -> |vim.treesitter.query.get()|
  • *vim.treesitter.parse_query()*         -> |vim.treesitter.query.parse()|
  • *vim.treesitter.query.parse_query()*   -> |vim.treesitter.query.parse()|
  • *vim.treesitter.add_predicate()*       -> |vim.treesitter.query.add_predicate()|
  • *vim.treesitter.add_directive()*       -> |vim.treesitter.query.add_directive()|
  • *vim.treesitter.list_predicates()*     -> |vim.treesitter.query.list_predicates()|
  • *vim.treesitter.list_directives()*     -> |vim.treesitter.query.list_directives()|
  • *vim.treesitter.query.get_range()*     -> |vim.treesitter.get_range()|
  • *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|

LUA
  • *nvim_exec()*				Use |nvim_exec2()| instead.
  • *vim.pretty_print()*			Use |vim.print()| instead.


------------------------------------------------------------------------------
DEPRECATED IN 0.8 OR EARLIER

API
• *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
• *nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
• *nvim_command_output()*	Use |nvim_exec2()| instead.
• *nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
• *nvim_get_option_info()*	Use |nvim_get_option_info2()| instead.

COMMANDS
• *:rv* *:rviminfo*		Deprecated alias to |:rshada| command.
• *:wv* *:wviminfo*		Deprecated alias to |:wshada| command.

ENVIRONMENT VARIABLES
• *$NVIM_LISTEN_ADDRESS*
  • Deprecated way to:
    • set the server name (use |--listen| or |serverstart()| instead)
    • get the server name (use |v:servername| instead)
    • detect a parent Nvim (use |$NVIM| instead)
  • Ignored if --listen is given.
  • Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
    option. Example: >vim
	call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername  } })
<

EVENTS
• *BufCreate*		Use |BufAdd| instead.
• *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
• *FileEncoding*	Never fired; equivalent to |EncodingChanged|.
• *GUIEnter*		Never fired; use |UIEnter| instead.
• *GUIFailed*		Never fired.

KEYCODES
• *<MouseDown>*		Use <ScrollWheelUp> instead.
• *<MouseUp>*		Use <ScrollWheelDown> instead.

HIGHLIGHTS
• *hl-VertSplit*	Use |hl-WinSeparator| instead.

LSP DIAGNOSTICS
For each of the functions below, use the corresponding function in
|vim.diagnostic| instead (unless otherwise noted). For example, use
|vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|.

• *vim.lsp.diagnostic.clear()*		Use |vim.diagnostic.hide()| instead.
• *vim.lsp.diagnostic.disable()*          Use |vim.diagnostic.enable()| instead.
• *vim.lsp.diagnostic.display()*	Use |vim.diagnostic.show()| instead.
• *vim.lsp.diagnostic.enable()*
• *vim.lsp.diagnostic.get()*
• *vim.lsp.diagnostic.get_all()*	Use |vim.diagnostic.get()| instead.
• *vim.lsp.diagnostic.get_count()*	Use |vim.diagnostic.count()| instead.
• *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead.
• *vim.lsp.diagnostic.get_next()*
• *vim.lsp.diagnostic.get_next_pos()*
• *vim.lsp.diagnostic.get_prev()*
• *vim.lsp.diagnostic.get_prev_pos()*
• *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* No replacement. Use
  options provided by |vim.diagnostic.config()| to customize virtual text.
• *vim.lsp.diagnostic.goto_next()*
• *vim.lsp.diagnostic.goto_prev()*
• *vim.lsp.diagnostic.redraw()*		Use |vim.diagnostic.show()| instead.
• *vim.lsp.diagnostic.reset()*
• *vim.lsp.diagnostic.save()*		Use |vim.diagnostic.set()| instead.
• *vim.lsp.diagnostic.set_loclist()*	Use |vim.diagnostic.setloclist()| instead.
• *vim.lsp.diagnostic.set_qflist()*	Use |vim.diagnostic.setqflist()| instead.
• *vim.lsp.diagnostic.show_line_diagnostics()* Use |vim.diagnostic.open_float()| instead.
• *vim.lsp.diagnostic.show_position_diagnostics()* Use |vim.diagnostic.open_float()| instead.

The following are deprecated without replacement. These functions are moved
internally and are no longer exposed as part of the API. Instead, use
|vim.diagnostic.config()| and |vim.diagnostic.show()|.

• *vim.lsp.diagnostic.set_signs()*
• *vim.lsp.diagnostic.set_underline()*
• *vim.lsp.diagnostic.set_virtual_text()*

LSP FUNCTIONS
• *vim.lsp.buf.server_ready()*
  Use |LspAttach| instead, depending on your use-case. "Server ready" is not
  part of the LSP spec, so the Nvim LSP client cannot meaningfully implement
  it. "Ready" is ambiguous because:
  • Language servers may finish analyzing the workspace, but edits can always
    re-trigger analysis/builds.
  • Language servers can serve some requests even while processing changes.
• *vim.lsp.buf.range_code_action()*		Use |vim.lsp.buf.code_action()| with
						the `range` parameter.
• *vim.lsp.util.diagnostics_to_items()*		Use |vim.diagnostic.toqflist()| instead.
• *vim.lsp.util.set_qflist()*			Use |setqflist()| instead.
• *vim.lsp.util.set_loclist()*			Use |setloclist()| instead.
• *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_clients()| with
						{buffer=bufnr} instead.
• *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
						{async=true} instead.
• *vim.lsp.buf.formatting_sync()*		Use |vim.lsp.buf.format()| with
						{async=false} instead.
• *vim.lsp.buf.range_formatting()*		Use |vim.lsp.formatexpr()|
						or |vim.lsp.buf.format()| instead.

LUA
• vim.register_keystroke_callback()	Use |vim.on_key()| instead.

NORMAL COMMANDS
• *]f* *[f*		Same as "gf".

OPTIONS
• *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special*
  `<>` notation is always enabled.
• *'fe'*		'fenc'+'enc' before Vim 6.0; no longer used.
• *'highlight'* *'hl'*	Names of builtin |highlight-groups| cannot be changed.
• *'langnoremap'*	Deprecated alias to 'nolangremap'.
• 'sessionoptions'	Flags "unix", "slash" are ignored and always enabled.
• *'vi'*
• 'viewoptions'		Flags "unix", "slash" are ignored and always enabled.
• *'viminfo'*		Deprecated alias to 'shada' option.
• *'viminfofile'*	Deprecated alias to 'shadafile' option.
• *'paste'* *'nopaste'*	Just Paste It.™  The 'paste' option is obsolete:
			|paste| is handled automatically when you paste text
			using your terminal's or GUI's paste feature
			(CTRL-SHIFT-v, CMD-v (macOS), middle-click, …).
			Enables "paste mode":
			  • Disables mappings in Insert, Cmdline mode.
			  • Disables abbreviations.
			  • Resets 'autoindent' 'expandtab' 'revins' 'ruler'
			    'showmatch' 'smartindent' 'smarttab' 'softtabstop'
			    'textwidth' 'wrapmargin'.
			  • Treats 'formatoptions' as empty.
			  • Disables the effect of these options:
			    • 'cindent'
			    • 'indentexpr'
			    • 'lisp'

UI EXTENSIONS
• *ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
			by the `ext_wildmenu` |ui-option|. Emits these events:
			• `["wildmenu_show", items]`
			• `["wildmenu_select", selected]`
			• `["wildmenu_hide"]`
• *term_background*	Unused. The terminal background color is now detected
			by the Nvim core directly instead of the TUI.

VARIABLES
• *b:terminal_job_pid*	Use `jobpid(&channel)` instead.
• *b:terminal_job_id*	Use `&channel` instead. To access in non-current buffer:
			• Lua: `vim.bo[bufnr].channel`
			• Vimscript: `getbufvar(bufnr, '&channel')`

VIMSCRIPT
• *buffer_exists()*	Obsolete name for |bufexists()|.
• *buffer_name()*	Obsolete name for |bufname()|.
• *buffer_number()*	Obsolete name for |bufnr()|.
• *file_readable()*	Obsolete name for |filereadable()|.
• *highlight_exists()*	Obsolete name for |hlexists()|.
• *highlightID()*	Obsolete name for |hlID()|.
• *inputdialog()*	Use |input()| instead.
• *jobclose()*		Obsolete name for |chanclose()|
• *jobsend()*		Obsolete name for |chansend()|
• *last_buffer_nr()*	Obsolete name for bufnr("$").
• *rpcstart()*		Use |jobstart()| with `{'rpc': v:true}` instead.
• *rpcstop()*		Use |jobstop()| instead to stop any job, or
			`chanclose(id, "rpc")` to close RPC communication
			without stopping the job. Use chanclose(id) to close
			any socket.