MARVIM Technical Documentation

"A sophisticated Neovim configuration that combines the logical precision of Vulcan engineering with the wisdom of Istari craftsmanship."

Overview

MARVIM is a high-performance Neovim configuration built on lazy.nvim with a modular, complexity-aware architecture. It emphasizes performance, maintainability, and developer experience through thoughtful abstraction layers and defensive programming patterns.

Architecture Principles

1. Modular Hierarchy

lua/
├── config/              # Core configuration layer
│   ├── autocmds.lua     # Event-driven automation
│   ├── lazy.lua         # Plugin manager setup
│   ├── options.lua      # Editor settings
│   ├── keymaps/         # Centralized keymap system
│   │   ├── keymaps.lua  # Main coordinator & exports
│   │   ├── core.lua     # Editor/window/buffer keymaps
│   │   ├── lsp.lua      # LSP & Git callback setups
│   │   ├── plugins.lua  # Plugin key table definitions
│   │   ├── search.lua   # Search-related operations
│   │   └── root.lua     # Root directory operations
│   └── plugins/         # Plugin specifications
│       ├── [category].lua      # Category aggregators
│       └── [category]/         # Complex configurations
├── utils/               # Utility libraries
│   ├── keymaps.lua      # Keymap management & safety
│   ├── lsp.lua          # LSP utilities & formatting
│   ├── root.lua         # Project root detection
│   └── theme.lua        # Color system & utilities
└── init.lua             # Entry point & bootstrap

2. Cognitive Complexity-Based Organization

Plugin configurations are organized by complexity:

LOW Complexity: Simple opts tables → Consolidated in category files
MEDIUM Complexity: Moderate configuration → Judgment call based on importance
HIGH Complexity: Extensive setup, critical functionality → Dedicated files

Example Structure:

lua/config/plugins/
├── lsp.lua              # Imports and simple LSP plugins
├── lsp/
│   ├── config.lua       # Complex LSP server setup
│   ├── mason.lua        # Tool management
│   └── completion.lua   # Advanced completion config
├── editor.lua           # Consolidates simple editor plugins
└── editor/
    ├── mini.lua         # Complex mini.nvim configurations
    └── oil.lua          # File explorer configuration

Plugin Management System

Lazy.nvim Integration

Bootstrap Process:

-- init.lua flow
1. Bootstrap lazy.nvim (auto-install if missing)
2. Load core configurations
3. Setup lazy with category imports
4. Lazy loading with performance optimizations

Category Import System:

-- lazy.lua setup
{
  { import = "config.plugins.core" },
  { import = "config.plugins.editor" },
  { import = "config.plugins.coding" },
  { import = "config.plugins.lsp" },
  { import = "config.plugins.git" },
  { import = "config.plugins.ui" },
  { import = "config.plugins.testing" },
  { import = "config.plugins.extras" },
}

Performance Optimizations:

Disabled built-in plugins: netrw, gzip, zipPlugin, etc.
Module caching enabled
Lazy-by-default loading strategy
Strategic eager loading for critical plugins

Plugin Categories

Core Plugins

plenary.nvim: Lua utilities foundation
which-key.nvim: Keymap discovery and documentation
persistence.nvim: Session management
dressing.nvim: UI enhancement for vim.ui

Editor Plugins

oil.nvim: Buffer-based file explorer
mini.nvim: Comprehensive editor enhancements
- mini.ai: Advanced text objects
- mini.surround: Surround operations
- mini.pairs: Auto-pairing
- mini.comment: Comment operations
flash.nvim: Enhanced navigation and search
toggleterm.nvim: Terminal management

LSP & Completion

nvim-lspconfig: LSP client configurations
mason.nvim: Tool installation manager
blink.cmp: High-performance completion engine
conform.nvim: Formatting with fallback chains

Git Integration

lazygit.nvim: Git GUI integration
gitsigns.nvim: Git status in gutter
diffview.nvim: Advanced diff views

Testing Framework

neotest: Test runner with adapters for:
- Jest/Vitest (JS/TS)
- pytest (Python)
- go test (Go)
- PHPUnit (PHP)

Keymap Architecture

Revolutionary Centralized System

MARVIM implements a fully centralized keymap system - the single source of truth for ALL keybindings.

Core Principle: Zero vim.keymap.set calls exist in plugin files.

Architecture Components

1. Main Coordinator (`lua/config/keymaps.lua`)

-- Exports plugin key tables
M.neotest_keys = { ... }
M.oil_keys = { ... }
M.trouble_keys = { ... }

-- Provides setup functions
M.setup_deferred()
M.setup_lsp_keybindings(client, buffer)

2. Modular Organization

core.lua: Editor, window, buffer, tab, terminal operations
lsp.lua: LSP and Git callback setup functions
plugins.lua: Plugin-specific key table definitions
search.lua: Search and navigation keymaps
root.lua: Project root operations

3. Safety Layer (`lua/utils/keymaps.lua`)

-- Conflict detection and error handling
safe_keymap_set(mode, lhs, rhs, opts)
register_keymap_conflict(key, plugin1, plugin2)
get_keymap_diagnostics()

Plugin Integration Pattern

-- In keymaps.lua
M.plugin_keys = {
  { "<leader>xx", function() require("plugin").action() end, desc = "Action" },
}

-- In plugin config
{
  "plugin-name",
  keys = function() return require("config.keymaps").plugin_keys end,
  opts = { ... },
}

Safety Features

Conflict Detection: Tracks and warns about keymap collisions
Error Handling: Graceful handling of failed registrations
Diagnostic Command: :KeymapDiagnostics shows conflicts
Deferred Setup: Avoids timing issues with plugin loading

LSP Configuration

Multi-layered Architecture

1. Utility Layer (`utils/lsp.lua`)

-- Core LSP utilities
M.get_clients(opts)           -- Enhanced client retrieval
M.on_attach(client, buffer)   -- Standard attachment callback
M.format(opts)                -- Formatting with fallbacks
M.get_root()                  -- Project root detection

2. Configuration Layer (`plugins/lsp/config.lua`)

-- Server setup and capabilities
local servers = {
  vtsls = { ... },      -- TypeScript/JavaScript
  lua_ls = { ... },     -- Lua
  pyright = { ... },    -- Python
  gopls = { ... },      -- Go
  -- Additional servers...
}

3. Tool Management (`plugins/lsp/mason.lua`)

-- Automatic tool installation
ensure_installed = {
  -- LSP servers
  "vtsls", "lua-language-server", "pyright",
  -- Formatters
  "prettier", "stylua", "black",
  -- Linters
  "eslint_d", "ruff",
}

Advanced Features

Capabilities Detection: Auto-detects blink.cmp vs nvim-cmp
Graceful Fallbacks: Handles missing dependencies
TypeScript Enhancement: Advanced vtsls configuration
Format Chains: Multiple formatter fallbacks per filetype

Utility Systems

Root Detection (`utils/root.lua`)

Comprehensive Project Detection:

-- 32 different project markers
local root_patterns = {
  ".git", ".hg", ".svn",
  "package.json", "Cargo.toml", "go.mod",
  "pyproject.toml", "setup.py", "requirements.txt",
  -- ... and many more
}

Performance Features:

Caching system for repeated lookups
Auto-setup via autocmds
Fallback to current directory

Theme System (`utils/theme.lua`)

Rose Pine Integration:

-- Semantic color mapping
local colors = {
  bg = "#191724",           -- Base background
  fg = "#e0def4",           -- Main foreground
  accent = "#ebbcba",       -- Primary accent
  muted = "#6e6a86",        -- Secondary text
  -- ... complete palette
}

Color Utilities:

M.darken(color, amount)     -- Darken color by percentage
M.lighten(color, amount)    -- Lighten color by percentage
M.alpha(color, alpha)       -- Apply alpha transparency
M.setup_highlights()        -- Apply custom highlights

Keymap Safety (`utils/keymaps.lua`)

Industrial-Grade Keymap Management:

-- Conflict detection registry
local keymap_registry = {}
local conflicts = {}
local errors = {}

-- Safe keymap registration
M.safe_keymap_set = function(mode, lhs, rhs, opts)
  -- Validation and conflict detection
  -- Error handling and logging
  -- Registration tracking
end

Performance Optimizations

MARVIM achieves exceptional startup performance (sub-40ms) through aggressive optimization strategies:

LSP Performance Engineering

Cached Capabilities: LSP capabilities calculated once and cached in lua/utils/lsp_cache.lua
Lazy Server Configs: Heavy server configurations extracted to lua/utils/lsp_servers.lua and loaded on-demand
Deferred Features: Codelens and inlay hints activate only after cursor activity (CursorHold/CursorHoldI)
Background Setup: Mason server installation happens asynchronously via vim.defer_fn()
Optimized Events: LSP loads on BufReadPre instead of BufReadPost for faster file opening

Completion System Optimization

Snippet Deferral: friendly-snippets and LuaSnip load only when :EnableSnippets is called
Minimal Default Sources: Completion uses only lsp, path, and buffer by default
Event Optimization: Removed CmdlineEnter trigger to eliminate 40ms+ bottleneck
Lazy Dependencies: Heavy completion dependencies marked as lazy = true

Plugin Loading Strategy

Strategic Event Triggers: Plugins load on precise events rather than broad categories
Dependency Management: Heavy dependencies (LuaSnip, friendly-snippets) deferred until needed
Deferred Initialization: Non-critical features initialize after UI is ready via autocmds

Startup Optimization Metrics

Original Performance: 201ms startup time
After LSP Optimization: 41ms startup time (80% improvement)
After Completion Optimization: 38ms startup time (81% total improvement)
Performance Monitoring: Use :Lazy profile to identify bottlenecks

Key Performance Utilities

lua/utils/lsp_cache.lua - LSP capability caching system
lua/utils/lsp_servers.lua - Deferred server configuration loading
Background mason setup with 50ms delay
CursorHold/CursorHoldI triggered feature loading for non-essential components

Runtime Performance

Root Caching: Project root detection cached
Capability Detection: LSP capabilities cached and reused
Keymap Registry: Efficient conflict detection
Selective Loading: Only load what's needed when needed

Development Workflow

Essential Commands

# Health checks
:checkhealth                  # System health
:checkhealth lazy            # Plugin health
:Mason                       # Tool management
:LspInfo                     # LSP status

# Performance & Diagnostics
:Lazy profile               # Plugin performance analysis
:KeymapDiagnostics          # Keymap conflicts
:EnableSnippets             # Load snippet support on-demand

# Performance monitoring
:Lazy profile               # Startup performance breakdown

Key Bindings by Category

File Operations

<leader>ff - Find files
<leader>fg - Live grep
<leader>fb - Browse buffers
<leader>fr - Recent files

Git Workflow

<leader>gg - LazyGit
<leader>gd - Diff view
<leader>gb - Git blame
<leader>gh - Git hunks

Testing

<leader>tt - Run nearest test
<leader>tf - Run file tests
<leader>ts - Test summary
<leader>tw - Watch tests

LSP Operations

gd - Go to definition
gr - Find references
K - Hover documentation
<leader>ca - Code actions

Troubleshooting

Common Issues

Plugin Loading: Check :Lazy for errors
LSP Problems: Use :LspInfo and :checkhealth lsp
Keymap Conflicts: Run :KeymapDiagnostics
Performance: Use :Lazy profile for bottlenecks

Debug Mode

-- Enable debug logging
vim.g.marvim_debug = true

Health Checks

:checkhealth                 # Full system check
:checkhealth lazy           # Plugin manager
:checkhealth mason          # Tool manager
:checkhealth lsp            # LSP configuration

Extending MARVIM

Adding New Plugins

Determine Complexity: Simple config → category file, complex → separate file
Add Keymaps: Update lua/config/keymaps/plugins.lua
Follow Patterns: Use existing plugins as templates

Custom Configurations

User Config: Create lua/user/ directory for personal customizations
Override Patterns: Use lazy.nvim's override system
Maintain Modularity: Keep changes isolated and reversible

Contributing

Follow Architecture: Respect complexity-based organization
Update Documentation: Keep DOCS.md current
Test Thoroughly: Verify no regressions
Performance: Profile changes with :Lazy profile

Conclusion

MARVIM represents a sophisticated approach to Neovim configuration, combining performance optimization with maintainable architecture. The centralized keymap system, complexity-based organization, and defensive programming patterns create a robust foundation for modern development workflows.

"In the grand tradition of both Starfleet engineering and Istari wisdom, MARVIM demonstrates that true sophistication lies not in complexity, but in the elegant orchestration of simple, well-designed components."

Version: 1.0
Last Updated: 2025-06-27
Author: Brendan Mullins
Architecture: Modular, Performance-Optimized
Plugin Manager: lazy.nvim

FilesExpand file tree

DOCS.md

Latest commit

History