config-auditing

Neovim Configuration Auditing Skill

Systematic configuration analysis for identifying issues, optimizations, and deprecated API usage in Neovim setups.

Supporting Documents

| Document | Purpose | When to Use | |----------|---------|-------------| | [audit-checklist.md](audit-checklist.md) | Structured audit categories with detection patterns | Systematic config review | | [best-practices.md](best-practices.md) | lazy.nvim patterns, vim.opt usage, keymap conventions | Optimization suggestions | | [deprecated-apis.md](deprecated-apis.md) | Version-specific deprecated APIs with grep patterns | Compatibility checks |

Quick Validation Commands

Run these headless commands for rapid assessment:

# Get Neovim version
nvim --version | head -1

# Get config path
nvim --headless -c "lua print(vim.fn.stdpath('config'))" -c "qa" 2>&1

# Count Lua files in config
find ~/.config/nvim -name "*.lua" 2>/dev/null | wc -l

# Count plugins (lazy.nvim)
ls ~/.local/share/nvim/lazy 2>/dev/null | wc -l

# Check for deprecated vim.api.nvim_buf_set_option usage
grep -rn "nvim_buf_set_option\|nvim_win_set_option" ~/.config/nvim --include="*.lua" 2>/dev/null | head -10

# Check startup time
nvim --startuptime /tmp/nvim-startup.log +q && tail -5 /tmp/nvim-startup.log

# Validate Lua syntax in config
nvim --headless -c "lua dofile(vim.fn.stdpath('config')..'/init.lua')" -c "qa" 2>&1

# Check for error on startup
nvim --headless -c "qa" 2>&1 | head -20

Scoring Criteria

Assign grades based on issue severity and count:

| Grade | Criteria | Description | |-------|----------|-------------| | A | 0 Critical, 0-2 Warnings | Excellent - Production ready | | B | 0 Critical, 3-5 Warnings | Good - Minor improvements possible | | C | 0 Critical, 6+ Warnings OR 1 Critical | Acceptable - Needs attention | | D | 2-3 Critical issues | Poor - Significant problems | | F | 4+ Critical issues | Failing - Requires immediate fixes |

Issue Severity Definitions

Critical: Security risks, breaking deprecated APIs (removed in current version), runtime errors Warning: Performance issues, deprecated APIs (still working), code style violations Suggestion: Optional improvements, modern alternatives, organization tips

Audit Workflow

1. Gather Environment Info
2. Neovim version (determines which deprecated APIs apply)
3. Plugin manager type (lazy.nvim, packer.nvim, etc.)
4. Config structure (single file vs modular)

1. Run Category Audits
2. Follow [audit-checklist.md](audit-checklist.md) categories in order
3. Use grep patterns to detect issues programmatically
4. Note severity for each finding

1. Check Version Compatibility
2. Reference [deprecated-apis.md](deprecated-apis.md) for user's Neovim version
3. Flag APIs deprecated OR removed in their version

1. Apply Best Practices
2. Compare against [best-practices.md](best-practices.md)
3. Suggest optimizations where applicable

1. Calculate Grade
2. Count Critical/Warning/Suggestion issues
3. Apply scoring criteria above
4. Provide overall health assessment

Output Template

<audit_report>
## Summary
- **Grade**: [A-F]
- **Neovim Version**: [detected version]
- **Config Location**: [path]
- **Plugin Count**: [count]

## Critical Issues
[List each critical issue with file:line and fix]

## Warnings
[List each warning with file:line and recommendation]

## Suggestions
[List optional improvements]

## Statistics
| Metric | Value |
|--------|-------|
| Total Lua files | X |
| Total lines | Y |
| Plugins | Z |
| Startup time | Nms |
| Deprecated APIs | N |
</audit_report>