# Neovim Java IDE Configuration

Custom Neovim configuration based on [kickstart.nvim](https://github.com/advpetc/kickstart.nvim) with enhanced Java development support.

## 🚀 Features

### Java Development
- **jdtls (Java Language Server)** - Full IDE features for Java
- **google-java-format** - Automatic code formatting
- **Gradle/Maven support** - Project detection and configuration
- **Syntax highlighting** - Java, Groovy, and Kotlin via Treesitter

### Code Navigation
- **Go to definition** (`grd`)
- **Go to implementation** (`gri`)
- **Find references** (`grr`)
- **Rename symbol** (`grn`)
- **Code actions** (`gra`)
- **Hover documentation** (`K`)

### IDE Features
- **Telescope fuzzy finder** - Fast file/text search
- **LSP-powered completion** - Intelligent auto-completion
- **Format on save** - Automatic code formatting
- **Relative line numbers** - Easier code navigation
- **Nerd Font icons** - Beautiful UI with icons

## 📦 What's Installed

### Plugins (22 total)
- **lazy.nvim** - Plugin manager
- **mason.nvim** - LSP/tool installer
- **nvim-lspconfig** - LSP configuration
- **nvim-treesitter** - Syntax highlighting
- **telescope.nvim** - Fuzzy finder
- **blink.cmp** - Auto-completion
- **conform.nvim** - Code formatting
- **gitsigns.nvim** - Git integration
- **which-key.nvim** - Keybinding helper
- **mini.nvim** - Utilities (statusline, surround, etc.)
- **tokyonight.nvim** - Color scheme

### LSP Servers
- **jdtls** - Java Language Server
- **lua_ls** - Lua Language Server

### Formatters
- **google-java-format** - Java formatter
- **stylua** - Lua formatter

## 🎨 UI Enhancements

### Nerd Font
- **Enabled**: `vim.g.have_nerd_font = true`
- **Recommended font**: JetBrainsMono Nerd Font
- **Installed at**: `~/Library/Fonts/JetBrainsMonoNerdFont-*.ttf`

### Display Settings
- **Line numbers**: Enabled with relative numbers
- **Color scheme**: Tokyo Night (dark theme)
- **Status line**: Mini.nvim statusline with icons
- **Cursor line**: Highlighted current line

## ⌨️ Key Bindings

### Navigation
| Keys | Action | Description |
|------|--------|-------------|
| `<Space>sf` | Search Files | Fuzzy find files |
| `<Space>sg` | Search Grep | Search text in files |
| `<Space>sw` | Search Word | Search current word |
| `<Space><Space>` | Buffers | Switch between open files |
| `<Space>s.` | Recent Files | Recently opened files |

### LSP Features
| Keys | Action | Description |
|------|--------|-------------|
| `grd` | Go to Definition | Jump to where symbol is defined |
| `gri` | Go to Implementation | Jump to implementation |
| `grr` | Find References | Find all references |
| `grn` | Rename | Rename symbol |
| `gra` | Code Action | Show code actions |
| `grt` | Type Definition | Jump to type definition |
| `K` | Hover | Show documentation |

### Editing
| Keys | Action | Description |
|------|--------|-------------|
| `<Space>f` | Format | Format current buffer |
| `<Space>q` | Quickfix | Open diagnostic quickfix |

### Window Management
| Keys | Action | Description |
|------|--------|-------------|
| `Ctrl-h` | Left Window | Move focus left |
| `Ctrl-j` | Down Window | Move focus down |
| `Ctrl-k` | Up Window | Move focus up |
| `Ctrl-l` | Right Window | Move focus right |

### Jump History
| Keys | Action | Description |
|------|--------|-------------|
| `Ctrl-o` | Jump Back | Previous location |
| `Ctrl-i` | Jump Forward | Next location |
| `Ctrl-^` | Alternate File | Toggle last two files |

## 📥 Installation Guide

### Prerequisites

Before installing, ensure you have:

#### 1. Neovim (Latest Stable or Nightly)

**macOS (using Homebrew):**
```bash
brew install neovim
```

**Verify installation:**
```bash
nvim --version
# Should show v0.10.0 or higher
```

#### 2. External Dependencies

**Required Tools:**
```bash
# macOS installation
brew install git make gcc ripgrep fd
```

**Java Development:**
```bash
# Install Java (if not already installed)
brew install openjdk@21

# Verify Java installation
java --version
```

**Optional but Recommended:**
- **Nerd Font** for icons: `brew install font-jetbrains-mono-nerd-font`
- **Clipboard tool**: Built-in on macOS (pbcopy/pbpaste)

### Installation Steps

#### Step 1: Backup Existing Configuration

If you have an existing Neovim configuration:

```bash
# Backup your current config
mv ~/.config/nvim ~/.config/nvim.backup.$(date +%Y%m%d_%H%M%S)

# Backup your data directory
mv ~/.local/share/nvim ~/.local/share/nvim.backup.$(date +%Y%m%d_%H%M%S)
```

#### Step 2: Install kickstart.nvim

**For personal use (Recommended):**

1. **Fork the repository:**
   - Go to: https://github.com/advpetc/kickstart.nvim
   - Click "Fork" button (top right)
   - This creates a copy under your GitHub account

2. **Clone your fork:**
```bash
# Replace <your_github_username> with your actual username
git clone https://github.com/<your_github_username>/kickstart.nvim.git ~/.config/nvim
```

**Or clone directly (not recommended for long-term use):**
```bash
git clone https://github.com/advpetc/kickstart.nvim.git ~/.config/nvim
```

#### Step 3: Apply Java IDE Enhancements

The Java enhancements are already included in this repository. If you're setting up from scratch:

1. **The `init.lua` file already contains:**
   - jdtls configuration (lines 743-828)
   - Java, Groovy, Kotlin Treesitter parsers (line 988)
   - google-java-format configuration (line 775)
   - Nerd Font enabled (line 94)
   - Relative line numbers (line 103)

2. **No additional configuration needed** - everything is ready to use!

#### Step 4: First Launch

```bash
nvim
```

**What happens on first launch:**
1. ✓ lazy.nvim plugin manager installs automatically
2. ✓ All 22 plugins download (~116MB, takes 1-2 minutes)
3. ✓ Treesitter parsers compile
4. ✓ Mason installs LSP servers (jdtls, lua_ls)
5. ✓ Native extensions build (telescope-fzf, LuaSnip)

**You'll see:**
```
 lazy.nvim
 ● nvim-lspconfig ... ✓
 ● telescope.nvim  ... ✓
 ● nvim-treesitter ... ✓
 [... 19 more plugins ...]
```

Press `q` to close the Lazy window when installation completes.

#### Step 5: Install Nerd Font (for icons)

```bash
# Install JetBrainsMono Nerd Font
brew install font-jetbrains-mono-nerd-font
```

**Configure your terminal:**

- **macOS Terminal:**
  1. Terminal → Preferences (Cmd+,)
  2. Profiles → Font → Change
  3. Select "JetBrainsMono Nerd Font Mono"
  4. Close and reopen Terminal

- **iTerm2:**
  1. iTerm2 → Settings (Cmd+,)
  2. Profiles → Text → Font
  3. Select "JetBrainsMono Nerd Font Mono"
  4. Restart iTerm2

#### Step 6: Test Java Features

```bash
# Open a test Java file
nvim /tmp/TestJava.java
```

Type this in the file:
```java
public class TestJava {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}
```

**Wait 5-10 seconds** for jdtls to start, then:

1. Run `:LspInfo` - Should show "Client: java"
2. Put cursor on `println` and press `K` - Shows documentation
3. Press `grd` on `println` - Jumps to definition
4. Press `<Space>f` - Formats the code

### Platform-Specific Installation

<details>
<summary><b>Windows Installation</b></summary>

**Using Chocolatey:**
```cmd
# Install Chocolatey first
winget install --accept-source-agreements chocolatey.chocolatey

# Install all requirements (run as admin)
choco install -y neovim git ripgrep wget fd unzip gzip mingw make
```

**Clone kickstart.nvim:**
```cmd
# Using cmd.exe
git clone https://github.com/advpetc/kickstart.nvim.git "%localappdata%\nvim"

# Using PowerShell
git clone https://github.com/advpetc/kickstart.nvim.git "${env:LOCALAPPDATA}\nvim"
```

**Install Java:**
```cmd
choco install -y openjdk
```
</details>

<details>
<summary><b>Linux Installation (Ubuntu/Debian)</b></summary>

**Ubuntu:**
```bash
# Add Neovim PPA
sudo add-apt-repository ppa:neovim-ppa/unstable -y
sudo apt update

# Install dependencies
sudo apt install make gcc ripgrep unzip git xclip neovim

# Install fd
sudo apt install fd-find

# Install Java
sudo apt install openjdk-21-jdk
```

**Debian:**
```bash
sudo apt update
sudo apt install make gcc ripgrep unzip git xclip curl

# Install Neovim manually
curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz
sudo rm -rf /opt/nvim-linux-x86_64
sudo mkdir -p /opt/nvim-linux-x86_64
sudo chmod a+rX /opt/nvim-linux-x86_64
sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz
sudo ln -sf /opt/nvim-linux-x86_64/bin/nvim /usr/local/bin/

# Install Java
sudo apt install openjdk-21-jdk
```

**Clone kickstart.nvim:**
```bash
git clone https://github.com/advpetc/kickstart.nvim.git ~/.config/nvim
```
</details>

<details>
<summary><b>Arch Linux Installation</b></summary>

```bash
# Install all dependencies
sudo pacman -S --noconfirm --needed gcc make git ripgrep fd unzip neovim jdk-openjdk

# Clone kickstart.nvim
git clone https://github.com/advpetc/kickstart.nvim.git ~/.config/nvim
```
</details>

<details>
<summary><b>Fedora Installation</b></summary>

```bash
# Install dependencies
sudo dnf install -y gcc make git ripgrep fd-find unzip neovim java-21-openjdk-devel

# Clone kickstart.nvim
git clone https://github.com/advpetc/kickstart.nvim.git ~/.config/nvim
```
</details>

### Verification

After installation, verify everything works:

```bash
# Check Neovim installation
nvim --version

# Check Java
java --version

# Check dependencies
which git make gcc rg fd

# Open Neovim
nvim

# Inside Neovim, run:
:checkhealth
```

The `:checkhealth` command will show the status of all components. Look for:
- ✓ Neovim version
- ✓ Git available
- ✓ ripgrep installed
- ✓ LSP servers installed
- ✓ Treesitter parsers installed

### Post-Installation

#### Configure Git (if needed)
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

#### Track Plugin Versions (Recommended)
```bash
cd ~/.config/nvim
# Remove lazy-lock.json from .gitignore to track plugin versions
git rm --cached lazy-lock.json
git add lazy-lock.json
git commit -m "Track plugin lock file"
```

### Alternative: Multiple Configurations

You can keep multiple Neovim configurations using `NVIM_APPNAME`:

```bash
# Install kickstart to a separate location
git clone https://github.com/advpetc/kickstart.nvim.git ~/.config/nvim-kickstart

# Create an alias
echo 'alias nvim-kick="NVIM_APPNAME=nvim-kickstart nvim"' >> ~/.zshrc
source ~/.zshrc

# Use the alternative config
nvim-kick  # Uses ~/.config/nvim-kickstart
nvim       # Uses ~/.config/nvim (your default)
```

## 🔧 Configuration Changes

### 1. Java LSP Setup (init.lua:743-828)

**Added dedicated jdtls configuration:**
```lua
{
  'neovim/nvim-lspconfig',
  ft = { 'java' },
  config = function()
    -- Auto-starts jdtls when opening .java files
    -- Creates unique workspace for each project
    -- Configures proper Java command-line arguments
  end,
}
```

**Key features:**
- Workspace directory: `~/.local/share/nvim/jdtls-workspace/<project-name>/`
- Auto-detects project root (git, Maven, Gradle)
- Memory allocation: 1GB heap size
- Supports Java 11+ modules

### 2. Treesitter Parsers (init.lua:988)

**Added language parsers:**
```lua
ensure_installed = {
  'bash', 'c', 'diff', 'html', 'lua', 'luadoc',
  'markdown', 'markdown_inline', 'query', 'vim', 'vimdoc',
  'java', 'groovy', 'kotlin'  -- Added for Java development
}
```

### 3. Mason Tools (init.lua:720-722)

**Added Java tools:**
```lua
ensure_installed = {
  'stylua',
  'jdtls',              -- Java Language Server
  'google-java-format', -- Java formatter
}
```

### 4. Code Formatting (init.lua:773-781)

**Added Java formatter:**
```lua
formatters_by_ft = {
  lua = { 'stylua' },
  java = { 'google-java-format' },  -- Added
}
```

### 5. UI Settings (init.lua:94, 103)

**Enabled enhancements:**
```lua
vim.g.have_nerd_font = true     -- Enable Nerd Font icons
vim.o.relativenumber = true     -- Relative line numbers
```

## 🚦 Getting Started

### First Launch
```bash
nvim
```

On first launch, Neovim will:
1. Install lazy.nvim plugin manager
2. Download all 22 plugins (~116MB)
3. Build native extensions (fzf, LuaSnip)
4. Install Mason tools (jdtls, formatters)

**This takes 1-2 minutes on first run.**

### Opening Java Files
```bash
cd your-java-project
nvim src/main/java/com/example/Main.java
```

**Wait 5-10 seconds** for jdtls to:
- Start the Language Server
- Index your project
- Enable LSP features

**Check status:**
```vim
:LspInfo
```
Should show: `Client: java (id: 1, bufnr: [1])`

### Testing LSP Features

**Try these in order:**
1. Put cursor on a method call → Press `grd` → Jump to definition
2. Press `K` over any method → Show documentation
3. Put cursor on a variable → Press `grr` → Find all references
4. Press `<Space>sf` → Search for files
5. Press `<Space>sg` → Search text in project

## 🔍 Troubleshooting

### LSP Not Working

**Check if jdtls is installed:**
```vim
:Mason
```
Look for "jdtls" in the list.

**Check LSP status:**
```vim
:LspInfo
```

**Restart LSP:**
```vim
:LspRestart
```

**Check for errors:**
```vim
:messages
```

### Java Features Not Available

**Symptoms:**
- "method not supported" errors
- No auto-completion
- `grr` doesn't work

**Solutions:**
1. **Wait** - First indexing takes 10-30 seconds
2. **Check file type:** `:set filetype?` should show `filetype=java`
3. **Verify jdtls running:** `:LspInfo` should show "Client: java"
4. **Large projects** - First indexing can take 30-60 seconds

### Nerd Font Icons Missing

**Symptoms:** Boxes/squares instead of icons

**Solution:**
1. Install Nerd Font: `brew install font-jetbrains-mono-nerd-font`
2. Configure terminal to use "JetBrainsMono Nerd Font Mono"
3. Restart terminal
4. Reopen Neovim

**Or disable icons:**
```lua
vim.g.have_nerd_font = false  -- in init.lua line 94
```

### Treesitter Error

**If you see:** `Failed to run config for nvim-treesitter`

**Already fixed in init.lua:982-999** - Uses `config = function()` instead of `main` parameter.

## 📁 Directory Structure

```
~/.config/nvim/
├── init.lua                    # Main configuration (1017 lines)
├── README.md                   # Original kickstart.nvim docs
├── JAVA_IDE_SETUP.md          # This file (custom setup docs)
└── lazy-lock.json             # Plugin versions (auto-generated)

~/.local/share/nvim/
├── lazy/                       # Plugins (22 plugins, 116MB)
├── mason/                      # LSP servers & tools
│   └── packages/
│       ├── jdtls/             # Java Language Server
│       └── google-java-format/ # Java formatter
├── jdtls-workspace/           # Java project workspaces
│   └── <project-name>/        # One per project
└── state/                      # Neovim state files

~/Library/Fonts/
└── JetBrainsMono*.ttf         # Nerd Font files

~/.config/nvim.backup.*/        # Backup of previous config
```

## 🔄 Updating

### Update Plugins
```vim
:Lazy update
```

### Update LSP Servers
```vim
:Mason
```
Press `U` to update all packages.

### Update Treesitter Parsers
```vim
:TSUpdate
```

## 📝 Customization

### Change Color Scheme
Edit `init.lua` line 897:
```lua
vim.cmd.colorscheme 'tokyonight-night'  -- or tokyonight-storm, tokyonight-moon, tokyonight-day
```

### Disable Format on Save
Edit `init.lua` line 759-771:
```lua
format_on_save = nil,  -- Change from function to nil
```

### Add More LSP Servers
Edit `init.lua` line 687-725:
```lua
local servers = {
  -- Add your server here
  pyright = {},    -- Python
  ts_ls = {},      -- TypeScript
  gopls = {},      -- Go
}
```

### Add Custom Keybindings
Add after line 200 in `init.lua`:
```lua
vim.keymap.set('n', '<Tab>', ':bnext<CR>', { desc = 'Next buffer' })
vim.keymap.set('n', '<S-Tab>', ':bprev<CR>', { desc = 'Previous buffer' })
```

## 📊 Performance

### Startup Time
- **Cold start**: ~200-300ms
- **With plugins**: ~250-350ms
- **With LSP**: +100-200ms (first file)

### Memory Usage
- **Base Neovim**: ~50MB
- **With plugins loaded**: ~80-100MB
- **With jdtls active**: ~150-200MB
- **Large Java projects**: ~300-500MB

### Indexing Time
- **Small project** (<1000 files): 5-10 seconds
- **Medium project** (<10k files): 20-30 seconds
- **Large project** (>10k files): 30-60 seconds

**Note:** Indexing is cached. Subsequent opens are much faster (2-3 seconds).

## 🆘 Support & Resources

### Documentation
- **Neovim docs**: `:help`
- **Search help**: `<Space>sh`
- **LSP help**: `:help lsp`
- **Telescope**: `:help telescope`
- **Treesitter**: `:help treesitter`

### Health Check
```vim
:checkhealth
```
Shows status of all components.

### Useful Commands
```vim
:Lazy           " Plugin manager
:Mason          " LSP installer
:LspInfo        " LSP status
:TSUpdate       " Update parsers
:ConformInfo    " Formatter info
:messages       " Show messages
```

## 🐛 Known Issues

1. **First Java file open is slow** - jdtls needs to start and index (normal behavior)
2. **Large projects may freeze briefly** - Initial indexing is CPU intensive
3. **Import organization** - Requires manual trigger with code action (`gra`)

## 📜 Version History

### 2026-01-26 - Java IDE Setup
- ✅ Installed kickstart.nvim base configuration
- ✅ Added jdtls with dedicated workspace setup
- ✅ Fixed jdtls configuration error (removed from standard LSP setup)
- ✅ Added Java, Groovy, Kotlin Treesitter parsers
- ✅ Installed google-java-format formatter
- ✅ Enabled relative line numbers
- ✅ Enabled Nerd Font icons
- ✅ Installed JetBrainsMono Nerd Font
- ✅ Backed up original init.vim config to `~/.config/nvim.backup.20260126_135707`

**Changes:** 107 insertions, 18 deletions (125 lines changed)

**Commit Message:**
```
Add Java development support with jdtls LSP configuration

- Configure jdtls (Java Language Server) with proper workspace setup
- Add support for Java, Groovy, and Kotlin syntax highlighting
- Enable google-java-format for automatic code formatting
- Add relative line numbers for easier code navigation
- Enable Nerd Font icons for better UI
- Fix jdtls configuration with dedicated FileType autocmd
- Add Mason tool installation for jdtls and google-java-format

This setup provides full IDE features for Java development including
go-to-definition, find references, code actions, and auto-completion.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
```

## 🎓 Learning Resources

### Neovim Basics
- `:Tutor` - Built-in tutorial
- `:help lua-guide` - Lua in Neovim
- `<Space>sh` - Search help docs

### LSP Features
- Learn `grd`, `gri`, `grr` navigation
- Use `K` for quick documentation
- Try `:LspInfo` to see active servers

### Telescope
- `<Space>sf` - Most used feature
- `<Space>sg` - Search in files
- `Ctrl-/` in Telescope - Show help

## 📄 License

Based on [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim) by TJ DeVries.

Configuration modifications by Claude Sonnet 4.5.

---

**System Info:**
- Neovim: v0.11.2
- Java: OpenJDK 21.0.6
- Platform: macOS (Darwin 25.2.0)
- Config location: `~/.config/nvim/init.lua`

**Last Updated:** 2026-01-26