@@ -0,0 +1,786 @@ |
| 1 | +# Language Server Protocol (LSP) Guide |
| 2 | + |
| 3 | +## What is LSP? |
| 4 | + |
| 5 | +**Language Server Protocol (LSP)** is like having a smart assistant that understands your programming language. It provides IDE-like features such as: |
| 6 | + |
| 7 | +- **Error detection** as you type |
| 8 | +- **Jump to definition** of functions/variables |
| 9 | +- **Find all references** to a symbol |
| 10 | +- **Auto-completion** suggestions |
| 11 | +- **Rename** symbols across your entire project |
| 12 | +- **Code formatting** to keep style consistent |
| 13 | +- **Quick fixes** for common errors |
| 14 | + |
| 15 | +Instead of building these features separately for each language, LSP uses a standardized protocol. This means `fac` can support Python, JavaScript, Fortran, Rust, and 100+ other languages using the same system! |
| 16 | + |
| 17 | +## How Does It Work? |
| 18 | + |
| 19 | +``` |
| 20 | +┌─────────────┐ LSP Protocol ┌──────────────────┐ |
| 21 | +│ │ ◄────────────────────────────► │ Language Server │ |
| 22 | +│ fac Editor │ (JSON messages over stdio) │ (e.g., pylsp) │ |
| 23 | +│ │ │ │ |
| 24 | +└─────────────┘ └──────────────────┘ |
| 25 | + │ │ |
| 26 | + │ You edit code │ Analyzes code |
| 27 | + │ Send changes │ Finds errors |
| 28 | + │ Request features │ Provides completions |
| 29 | +``` |
| 30 | + |
| 31 | +When you open a file in `fac`: |
| 32 | +1. `fac` starts the appropriate language server (e.g., `pylsp` for Python) |
| 33 | +2. `fac` tells the server what file you're editing |
| 34 | +3. As you type, `fac` sends your changes to the server |
| 35 | +4. The server analyzes your code and sends back diagnostics (errors/warnings) |
| 36 | +5. When you press F12, `fac` asks the server "where is this defined?" |
| 37 | +6. The server responds with the location, and `fac` jumps there |
| 38 | + |
| 39 | +## Quick Start |
| 40 | + |
| 41 | +### Step 1: Install a Language Server |
| 42 | + |
| 43 | +Language servers are separate programs you install once. Here are the most common ones: |
| 44 | + |
| 45 | +**Python:** |
| 46 | +```bash |
| 47 | +pip install python-lsp-server |
| 48 | +``` |
| 49 | + |
| 50 | +**JavaScript/TypeScript:** |
| 51 | +```bash |
| 52 | +npm install -g typescript-language-server typescript |
| 53 | +``` |
| 54 | + |
| 55 | +**Rust:** |
| 56 | +```bash |
| 57 | +rustup component add rust-analyzer |
| 58 | +``` |
| 59 | + |
| 60 | +**Fortran:** |
| 61 | +```bash |
| 62 | +pip install fortls |
| 63 | +``` |
| 64 | + |
| 65 | +**Go:** |
| 66 | +```bash |
| 67 | +go install golang.org/x/tools/gopls@latest |
| 68 | +``` |
| 69 | + |
| 70 | +**C/C++:** |
| 71 | +```bash |
| 72 | +# On macOS with Homebrew |
| 73 | +brew install llvm |
| 74 | +# clangd comes with LLVM |
| 75 | + |
| 76 | +# On Linux |
| 77 | +sudo apt install clangd |
| 78 | +``` |
| 79 | + |
| 80 | +See the **Language Server Setup** section below for detailed instructions. |
| 81 | + |
| 82 | +### Step 2: Open a File |
| 83 | + |
| 84 | +Just open `fac` with a source code file: |
| 85 | + |
| 86 | +```bash |
| 87 | +fac my_script.py |
| 88 | +``` |
| 89 | + |
| 90 | +That's it! If you have `pylsp` installed, `fac` will automatically: |
| 91 | +- Start the language server |
| 92 | +- Begin analyzing your code |
| 93 | +- Show errors/warnings with red/yellow markers in the gutter |
| 94 | +- Enable all LSP features |
| 95 | + |
| 96 | +### Step 3: Try It Out |
| 97 | + |
| 98 | +1. **See errors**: Look for `E` (error) or `W` (warning) in the left gutter |
| 99 | +2. **View all diagnostics**: Press `Ctrl+Shift+D` to open the diagnostics panel |
| 100 | +3. **Jump to definition**: Put cursor on a function name and press `F12` |
| 101 | +4. **Find references**: Press `Shift+F12` to see everywhere a symbol is used |
| 102 | +5. **Rename**: Press `F2` to rename a variable across all files |
| 103 | +6. **Format code**: Press `Shift+Alt+F` to auto-format |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## LSP Features Reference |
| 108 | + |
| 109 | +### 1. Diagnostics (Errors & Warnings) |
| 110 | + |
| 111 | +**What it does:** Shows syntax errors, type errors, and warnings as you code. |
| 112 | + |
| 113 | +**How to use:** |
| 114 | +- Errors appear with `E` in the gutter (red) |
| 115 | +- Warnings appear with `W` in the gutter (yellow) |
| 116 | +- Put your cursor on a line with an error to see the message in the status bar |
| 117 | +- Press `Ctrl+Shift+D` to open the **Diagnostics Panel** showing all issues |
| 118 | + |
| 119 | +**Example:** |
| 120 | +```python |
| 121 | +def greet(name): |
| 122 | + print("Hello, " + nme) # Error: 'nme' is not defined |
| 123 | + ^^^^^^^^^^^^^^^^^^^^ |
| 124 | + E: Undefined name 'nme' |
| 125 | +``` |
| 126 | + |
| 127 | +**Keybinding:** |
| 128 | +- `Ctrl+Shift+D` - Open/close diagnostics panel |
| 129 | +- `j`/`k` or `↑`/`↓` - Navigate issues in panel |
| 130 | +- `Enter` - Jump to selected issue |
| 131 | +- `Esc` - Close panel |
| 132 | + |
| 133 | +--- |
| 134 | + |
| 135 | +### 2. Go to Definition (F12) |
| 136 | + |
| 137 | +**What it does:** Jump to where a function, variable, or class is defined. |
| 138 | + |
| 139 | +**How to use:** |
| 140 | +1. Put your cursor on a symbol (function name, variable, class, etc.) |
| 141 | +2. Press `F12` |
| 142 | +3. `fac` jumps to the definition (opens file in new tab if needed) |
| 143 | +4. Press `Alt+,` to jump back to where you were |
| 144 | + |
| 145 | +**Example:** |
| 146 | +```python |
| 147 | +# In main.py |
| 148 | +result = calculate_total(items) |
| 149 | + ^^^^^^^^^^^^^^^ |
| 150 | + Put cursor here, press F12 |
| 151 | + |
| 152 | +# Jumps to utils.py: |
| 153 | +def calculate_total(items): # ← You land here |
| 154 | + return sum(item.price for item in items) |
| 155 | +``` |
| 156 | + |
| 157 | +**Keybindings:** |
| 158 | +- `F12` - Go to definition |
| 159 | +- `Alt+,` - Jump back (navigate backward in jump history) |
| 160 | + |
| 161 | +**Cross-file navigation:** If the definition is in another file, `fac` automatically opens it in a new tab! |
| 162 | + |
| 163 | +--- |
| 164 | + |
| 165 | +### 3. Find References (Shift+F12) |
| 166 | + |
| 167 | +**What it does:** Find all places where a symbol is used across your entire project. |
| 168 | + |
| 169 | +**How to use:** |
| 170 | +1. Put cursor on a symbol |
| 171 | +2. Press `Shift+F12` |
| 172 | +3. Browse references in the panel |
| 173 | +4. Press `Enter` to jump to a reference |
| 174 | + |
| 175 | +**Example:** |
| 176 | +```python |
| 177 | +# You want to find everywhere `calculate_total` is called |
| 178 | +def calculate_total(items): |
| 179 | + ... |
| 180 | + |
| 181 | +# Press Shift+F12 shows: |
| 182 | +References to 'calculate_total': |
| 183 | + main.py:15:12 - result = calculate_total(items) |
| 184 | + test.py:23:8 - assert calculate_total([]) == 0 |
| 185 | + utils.py:45:3 - total = calculate_total(cart.items) |
| 186 | +``` |
| 187 | + |
| 188 | +**Keybindings:** |
| 189 | +- `Shift+F12` - Find all references |
| 190 | +- `j`/`k` or `↑`/`↓` - Navigate references |
| 191 | +- `Enter` - Jump to selected reference |
| 192 | +- `Esc` - Close panel |
| 193 | + |
| 194 | +--- |
| 195 | + |
| 196 | +### 4. Code Actions & Quick Fixes (Ctrl+.) |
| 197 | + |
| 198 | +**What it does:** Get quick fixes for errors and refactoring suggestions. |
| 199 | + |
| 200 | +**How to use:** |
| 201 | +1. Put cursor on an error or piece of code |
| 202 | +2. Press `Ctrl+.` |
| 203 | +3. Select an action from the menu |
| 204 | +4. Press `Enter` to apply it |
| 205 | + |
| 206 | +**Example:** |
| 207 | +```python |
| 208 | +# Error: Missing import |
| 209 | +result = json.loads(data) |
| 210 | + ^^^^ |
| 211 | + Error: 'json' is not defined |
| 212 | + |
| 213 | +# Press Ctrl+. shows: |
| 214 | +Code Actions: |
| 215 | + → Import 'json' |
| 216 | + Ignore undefined name 'json' |
| 217 | + |
| 218 | +# Select "Import 'json'" and fac adds: |
| 219 | +import json # ← Automatically added! |
| 220 | +``` |
| 221 | + |
| 222 | +**Common actions:** |
| 223 | +- Add missing imports |
| 224 | +- Fix spelling errors in variable names |
| 225 | +- Extract method/function |
| 226 | +- Organize imports |
| 227 | +- Add type hints |
| 228 | + |
| 229 | +**Keybindings:** |
| 230 | +- `Ctrl+.` - Open code actions menu |
| 231 | +- `j`/`k` or `↑`/`↓` - Navigate actions |
| 232 | +- `Enter` - Apply selected action |
| 233 | +- `Esc` - Close menu |
| 234 | + |
| 235 | +--- |
| 236 | + |
| 237 | +### 5. Rename Symbol (F2) |
| 238 | + |
| 239 | +**What it does:** Rename a variable, function, or class everywhere it's used. |
| 240 | + |
| 241 | +**How to use:** |
| 242 | +1. Put cursor on a symbol |
| 243 | +2. Press `F2` |
| 244 | +3. Type the new name |
| 245 | +4. Press `Enter` |
| 246 | +5. The symbol is renamed everywhere across all files! |
| 247 | + |
| 248 | +**Example:** |
| 249 | +```python |
| 250 | +# Before: |
| 251 | +def calc(x, y): |
| 252 | + return x + y |
| 253 | + |
| 254 | +result = calc(5, 3) |
| 255 | +total = calc(10, 20) |
| 256 | + |
| 257 | +# Put cursor on 'calc', press F2, type 'calculate' |
| 258 | +# After: |
| 259 | +def calculate(x, y): |
| 260 | + return x + y |
| 261 | + |
| 262 | +result = calculate(5, 3) |
| 263 | +total = calculate(10, 20) |
| 264 | +``` |
| 265 | + |
| 266 | +**Safe renaming:** The language server understands your code's structure, so it won't accidentally rename: |
| 267 | +- String contents: `"call calc function"` stays unchanged |
| 268 | +- Comments: `# calc is fast` stays unchanged |
| 269 | +- Unrelated variables with the same name in different scopes |
| 270 | + |
| 271 | +**Keybinding:** |
| 272 | +- `F2` - Rename symbol |
| 273 | +- Type new name, press `Enter` to confirm |
| 274 | +- Press `Esc` to cancel |
| 275 | + |
| 276 | +--- |
| 277 | + |
| 278 | +### 6. Document Symbols Outline (Ctrl+Shift+O) |
| 279 | + |
| 280 | +**What it does:** See an outline of all functions, classes, and variables in the current file. |
| 281 | + |
| 282 | +**How to use:** |
| 283 | +1. Press `Ctrl+Shift+O` to open the symbols panel |
| 284 | +2. Type to filter symbols (fuzzy search) |
| 285 | +3. Press `Enter` to jump to a symbol |
| 286 | + |
| 287 | +**Example:** |
| 288 | +``` |
| 289 | +Document Symbols: |
| 290 | + [Class] User |
| 291 | + [Method] __init__ |
| 292 | + [Method] validate |
| 293 | + [Property] full_name |
| 294 | + [Function] create_user |
| 295 | + [Function] delete_user |
| 296 | + [Variable] DEFAULT_TIMEOUT |
| 297 | +``` |
| 298 | + |
| 299 | +**Keybindings:** |
| 300 | +- `Ctrl+Shift+O` - Open document symbols panel |
| 301 | +- Type to search (fuzzy matching) |
| 302 | +- `j`/`k` or `↑`/`↓` - Navigate symbols |
| 303 | +- `Enter` - Jump to selected symbol |
| 304 | +- `Esc` - Close panel |
| 305 | + |
| 306 | +--- |
| 307 | + |
| 308 | +### 7. Workspace Symbols (Ctrl+Shift+T) |
| 309 | + |
| 310 | +**What it does:** Search for any symbol across your **entire project** (all files). |
| 311 | + |
| 312 | +**How to use:** |
| 313 | +1. Press `Ctrl+Shift+T` to open workspace symbols |
| 314 | +2. Type part of a symbol name (fuzzy search) |
| 315 | +3. Navigate and press `Enter` to jump to it |
| 316 | + |
| 317 | +**Example:** |
| 318 | +``` |
| 319 | +# Type "calc" |
| 320 | +Workspace Symbols: |
| 321 | + [Function] calculate_total in utils.py |
| 322 | + [Function] calculator_init in calculator.py |
| 323 | + [Class] Calculator in calculator.py |
| 324 | + [Method] recalculate in models.py |
| 325 | + [Variable] CALC_PRECISION in config.py |
| 326 | +``` |
| 327 | + |
| 328 | +**Fuzzy search:** You don't need to type the exact name: |
| 329 | +- `calc` matches `calculate_total` |
| 330 | +- `ct` matches `calculate_total` (first letters) |
| 331 | +- `calctot` matches `calculate_total` (consecutive) |
| 332 | + |
| 333 | +**Keybindings:** |
| 334 | +- `Ctrl+Shift+T` - Open workspace symbols |
| 335 | +- Type to search across all files |
| 336 | +- `j`/`k` or `↑`/`↓` - Navigate results |
| 337 | +- `Enter` - Jump to symbol (opens file if needed) |
| 338 | +- `Esc` - Close panel |
| 339 | + |
| 340 | +**Pro tip:** This is incredibly fast for navigating large codebases! |
| 341 | + |
| 342 | +--- |
| 343 | + |
| 344 | +### 8. Signature Help |
| 345 | + |
| 346 | +**What it does:** Shows function parameters and types as you're typing a function call. |
| 347 | + |
| 348 | +**How to use:** |
| 349 | +Just start typing a function call with `(`, and a tooltip appears: |
| 350 | + |
| 351 | +**Example:** |
| 352 | +```python |
| 353 | +# You type: |
| 354 | +result = calculate_total( |
| 355 | + ^ |
| 356 | + Cursor here |
| 357 | + |
| 358 | +# Tooltip shows: |
| 359 | +calculate_total(items: list[Item], tax_rate: float = 0.0) -> float |
| 360 | + ^^^^^ |
| 361 | + Current parameter highlighted |
| 362 | +``` |
| 363 | + |
| 364 | +**Keybindings:** |
| 365 | +- Appears automatically when you type `(` |
| 366 | +- Type `,` to move to next parameter |
| 367 | +- Auto-dismisses when you type `)` |
| 368 | + |
| 369 | +**Works with:** |
| 370 | +- Regular functions |
| 371 | +- Class constructors |
| 372 | +- Methods |
| 373 | +- Overloaded functions (shows all signatures) |
| 374 | + |
| 375 | +--- |
| 376 | + |
| 377 | +### 9. Document Formatting (Shift+Alt+F) |
| 378 | + |
| 379 | +**What it does:** Automatically formats your code according to style guidelines. |
| 380 | + |
| 381 | +**How to use:** |
| 382 | +1. Press `Shift+Alt+F` |
| 383 | +2. Your code is instantly formatted |
| 384 | + |
| 385 | +**Example:** |
| 386 | +```python |
| 387 | +# Before: |
| 388 | +def greet( name,age ): |
| 389 | + if age>18: |
| 390 | + print( "Hello, "+name ) |
| 391 | + else:print("Hi, "+name) |
| 392 | + |
| 393 | +# After (Shift+Alt+F): |
| 394 | +def greet(name, age): |
| 395 | + if age > 18: |
| 396 | + print("Hello, " + name) |
| 397 | + else: |
| 398 | + print("Hi, " + name) |
| 399 | +``` |
| 400 | + |
| 401 | +**Respects:** |
| 402 | +- `.editorconfig` settings |
| 403 | +- Language-specific style guides (PEP 8 for Python, etc.) |
| 404 | +- Project configuration files (`.pylintrc`, `pyproject.toml`, etc.) |
| 405 | + |
| 406 | +**Keybinding:** |
| 407 | +- `Shift+Alt+F` - Format entire document |
| 408 | + |
| 409 | +**Formatters by language:** |
| 410 | +- Python: `black`, `autopep8`, or `yapf` (configured in `pylsp`) |
| 411 | +- JavaScript: `prettier` |
| 412 | +- Rust: `rustfmt` |
| 413 | +- Go: `gofmt` |
| 414 | + |
| 415 | +--- |
| 416 | + |
| 417 | +### 10. Command Palette (Ctrl+Shift+P) |
| 418 | + |
| 419 | +**What it does:** Quick access to all LSP commands without remembering keybindings. |
| 420 | + |
| 421 | +**How to use:** |
| 422 | +1. Press `Ctrl+Shift+P` |
| 423 | +2. Type to search commands (fuzzy search) |
| 424 | +3. Press `Enter` to execute |
| 425 | + |
| 426 | +**Available commands:** |
| 427 | +``` |
| 428 | +Command Palette: |
| 429 | + [LSP] Go to Definition |
| 430 | + [LSP] Find References |
| 431 | + [LSP] Rename Symbol |
| 432 | + [LSP] Code Actions |
| 433 | + [LSP] Document Symbols |
| 434 | + [LSP] Workspace Symbols |
| 435 | + [LSP] Format Document |
| 436 | + [File] Save File |
| 437 | + [Navigate] Jump Back |
| 438 | + ... and 40+ more! |
| 439 | +``` |
| 440 | + |
| 441 | +**Keybindings:** |
| 442 | +- `Ctrl+Shift+P` - Open command palette |
| 443 | +- Type to search commands |
| 444 | +- `Enter` - Execute selected command |
| 445 | +- `Esc` - Close palette |
| 446 | + |
| 447 | +--- |
| 448 | + |
| 449 | +## Language Server Setup |
| 450 | + |
| 451 | +### Python (pylsp) |
| 452 | + |
| 453 | +**Install:** |
| 454 | +```bash |
| 455 | +pip install python-lsp-server |
| 456 | + |
| 457 | +# Optional plugins for more features: |
| 458 | +pip install python-lsp-black # Black formatting |
| 459 | +pip install pylsp-mypy # Type checking |
| 460 | +pip install python-lsp-ruff # Fast linting |
| 461 | +``` |
| 462 | + |
| 463 | +**What you get:** |
| 464 | +- Error detection (syntax, undefined variables) |
| 465 | +- Auto-completion |
| 466 | +- Go to definition / Find references |
| 467 | +- Rename symbol |
| 468 | +- Code formatting (with black) |
| 469 | +- Type checking (with mypy) |
| 470 | + |
| 471 | +**Configuration:** |
| 472 | +Create `~/.config/pylsp/config.json`: |
| 473 | +```json |
| 474 | +{ |
| 475 | + "plugins": { |
| 476 | + "black": {"enabled": true}, |
| 477 | + "mypy": {"enabled": true} |
| 478 | + } |
| 479 | +} |
| 480 | +``` |
| 481 | + |
| 482 | +--- |
| 483 | + |
| 484 | +### JavaScript/TypeScript (typescript-language-server) |
| 485 | + |
| 486 | +**Install:** |
| 487 | +```bash |
| 488 | +npm install -g typescript-language-server typescript |
| 489 | +``` |
| 490 | + |
| 491 | +**What you get:** |
| 492 | +- Error detection (TypeScript type errors) |
| 493 | +- Auto-completion with type information |
| 494 | +- Refactoring (extract function, rename, etc.) |
| 495 | +- Import management |
| 496 | +- JSDoc support |
| 497 | + |
| 498 | +**Works with:** |
| 499 | +- JavaScript (`.js`) |
| 500 | +- TypeScript (`.ts`, `.tsx`) |
| 501 | +- JSX/React files |
| 502 | + |
| 503 | +--- |
| 504 | + |
| 505 | +### Rust (rust-analyzer) |
| 506 | + |
| 507 | +**Install:** |
| 508 | +```bash |
| 509 | +rustup component add rust-analyzer |
| 510 | +``` |
| 511 | + |
| 512 | +**What you get:** |
| 513 | +- Instant error detection |
| 514 | +- Powerful type inference |
| 515 | +- Macro expansion |
| 516 | +- Cargo integration |
| 517 | +- Inline type hints |
| 518 | + |
| 519 | +**Note:** Works best with `Cargo.toml` in your project root. |
| 520 | + |
| 521 | +--- |
| 522 | + |
| 523 | +### Fortran (fortls) |
| 524 | + |
| 525 | +**Install:** |
| 526 | +```bash |
| 527 | +pip install fortls |
| 528 | +``` |
| 529 | + |
| 530 | +**What you get:** |
| 531 | +- Syntax error detection |
| 532 | +- Module/subroutine navigation |
| 533 | +- Variable completion |
| 534 | +- Signature help |
| 535 | +- Hover documentation |
| 536 | + |
| 537 | +**Configuration:** |
| 538 | +Create `.fortls` in your project root: |
| 539 | +```json |
| 540 | +{ |
| 541 | + "lowercase_intrinsics": true, |
| 542 | + "hover_signature": true, |
| 543 | + "use_signature_help": true |
| 544 | +} |
| 545 | +``` |
| 546 | + |
| 547 | +--- |
| 548 | + |
| 549 | +### Go (gopls) |
| 550 | + |
| 551 | +**Install:** |
| 552 | +```bash |
| 553 | +go install golang.org/x/tools/gopls@latest |
| 554 | +``` |
| 555 | + |
| 556 | +**What you get:** |
| 557 | +- Error detection |
| 558 | +- Auto-imports |
| 559 | +- Refactoring tools |
| 560 | +- Test integration |
| 561 | +- Fast navigation |
| 562 | + |
| 563 | +--- |
| 564 | + |
| 565 | +### C/C++ (clangd) |
| 566 | + |
| 567 | +**Install:** |
| 568 | +```bash |
| 569 | +# macOS |
| 570 | +brew install llvm |
| 571 | + |
| 572 | +# Ubuntu/Debian |
| 573 | +sudo apt install clangd |
| 574 | + |
| 575 | +# Arch |
| 576 | +sudo pacman -S clang |
| 577 | +``` |
| 578 | + |
| 579 | +**What you get:** |
| 580 | +- Real-time error checking |
| 581 | +- Include path completion |
| 582 | +- Cross-reference navigation |
| 583 | +- Refactoring support |
| 584 | + |
| 585 | +**Configuration:** |
| 586 | +Create `compile_commands.json` in project root: |
| 587 | +```bash |
| 588 | +# With CMake: |
| 589 | +cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 . |
| 590 | + |
| 591 | +# With Make: |
| 592 | +bear -- make |
| 593 | +``` |
| 594 | + |
| 595 | +--- |
| 596 | + |
| 597 | +## Troubleshooting |
| 598 | + |
| 599 | +### "No language server found" |
| 600 | + |
| 601 | +**Problem:** `fac` can't find the language server executable. |
| 602 | + |
| 603 | +**Solution:** |
| 604 | +1. Make sure the language server is installed: |
| 605 | + ```bash |
| 606 | + which pylsp # For Python |
| 607 | + which rust-analyzer # For Rust |
| 608 | + which gopls # For Go |
| 609 | + ``` |
| 610 | + |
| 611 | +2. Make sure the executable is in your `PATH`: |
| 612 | + ```bash |
| 613 | + echo $PATH |
| 614 | + ``` |
| 615 | + |
| 616 | +3. Try running the language server manually: |
| 617 | + ```bash |
| 618 | + pylsp --help |
| 619 | + ``` |
| 620 | + |
| 621 | +--- |
| 622 | + |
| 623 | +### "LSP features not working" |
| 624 | + |
| 625 | +**Problem:** File opens but no diagnostics/features appear. |
| 626 | + |
| 627 | +**Solution:** |
| 628 | +1. Check if the server started: |
| 629 | + - Look in `fac`'s logs (if available) |
| 630 | + - The server might have crashed on startup |
| 631 | + |
| 632 | +2. Check file extension matches language: |
| 633 | + - `.py` → Python |
| 634 | + - `.rs` → Rust |
| 635 | + - `.f90`, `.f95` → Fortran |
| 636 | + |
| 637 | +3. Make sure the file is in a proper project structure: |
| 638 | + - Python: Have a `setup.py` or `pyproject.toml`? |
| 639 | + - Rust: Have a `Cargo.toml`? |
| 640 | + - Some servers need project metadata |
| 641 | + |
| 642 | +--- |
| 643 | + |
| 644 | +### "Diagnostics are slow/delayed" |
| 645 | + |
| 646 | +**Problem:** Errors appear several seconds after typing. |
| 647 | + |
| 648 | +**Explanation:** This is normal! Language servers analyze your code: |
| 649 | +- Simple syntax errors: ~100ms |
| 650 | +- Type checking: 500ms-2s |
| 651 | +- Full project analysis: 2-10s |
| 652 | + |
| 653 | +**Tips:** |
| 654 | +- `fac` debounces changes (waits 500ms after you stop typing) |
| 655 | +- Large projects take longer |
| 656 | +- First-time analysis is slower (builds cache) |
| 657 | + |
| 658 | +--- |
| 659 | + |
| 660 | +### "Server keeps crashing" |
| 661 | + |
| 662 | +**Problem:** LSP features work then suddenly stop. |
| 663 | + |
| 664 | +**Solution:** |
| 665 | +1. Check server version: |
| 666 | + ```bash |
| 667 | + pylsp --version |
| 668 | + ``` |
| 669 | + |
| 670 | +2. Update the language server: |
| 671 | + ```bash |
| 672 | + pip install --upgrade python-lsp-server |
| 673 | + ``` |
| 674 | + |
| 675 | +3. Check for conflicting plugins/extensions |
| 676 | + |
| 677 | +4. Restart `fac` |
| 678 | + |
| 679 | +--- |
| 680 | + |
| 681 | +### "Formatting changes my code unexpectedly" |
| 682 | + |
| 683 | +**Problem:** `Shift+Alt+F` makes unwanted changes. |
| 684 | + |
| 685 | +**Solution:** |
| 686 | +1. Check your formatter configuration |
| 687 | +2. Many formatters respect configuration files: |
| 688 | + - Python: `pyproject.toml` or `.pylintrc` |
| 689 | + - JavaScript: `.prettierrc` |
| 690 | + - Rust: `rustfmt.toml` |
| 691 | + |
| 692 | +3. Configure line length, indentation, etc. in those files |
| 693 | + |
| 694 | +--- |
| 695 | + |
| 696 | +## Tips & Tricks |
| 697 | + |
| 698 | +### 1. Use Jump Stack for Navigation |
| 699 | + |
| 700 | +After using F12 to jump to a definition: |
| 701 | +- Press `Alt+,` to jump back |
| 702 | +- Works across multiple jumps (maintains history) |
| 703 | +- Great for exploring unfamiliar codebases |
| 704 | + |
| 705 | +### 2. Combine Search Features |
| 706 | + |
| 707 | +- `Ctrl+F` - Search text in current file |
| 708 | +- `Ctrl+Shift+O` - Search symbols in current file |
| 709 | +- `Ctrl+Shift+T` - Search symbols across project |
| 710 | +- `Shift+F12` - Find all usages of current symbol |
| 711 | + |
| 712 | +### 3. Fix Errors Faster |
| 713 | + |
| 714 | +When you see an error: |
| 715 | +1. Press `Ctrl+Shift+D` to see all errors |
| 716 | +2. Navigate to each error |
| 717 | +3. Press `Ctrl+.` to see quick fixes |
| 718 | +4. Apply fixes with `Enter` |
| 719 | + |
| 720 | +### 4. Rename Safely |
| 721 | + |
| 722 | +Before renaming: |
| 723 | +- Press `Shift+F12` to see all references |
| 724 | +- Verify it's safe to rename |
| 725 | +- Press `F2` to rename everywhere at once |
| 726 | + |
| 727 | +### 5. Format on Save |
| 728 | + |
| 729 | +Many language servers support format-on-save: |
| 730 | +- Press `Ctrl+S` to save |
| 731 | +- File is automatically formatted |
| 732 | +- Keeps your code style consistent |
| 733 | + |
| 734 | +--- |
| 735 | + |
| 736 | +## LSP Keybindings Quick Reference |
| 737 | + |
| 738 | +| Feature | Keybinding | What It Does | |
| 739 | +|---------|-----------|--------------| |
| 740 | +| **Diagnostics Panel** | `Ctrl+Shift+D` | Show all errors/warnings | |
| 741 | +| **Go to Definition** | `F12` | Jump to where symbol is defined | |
| 742 | +| **Find References** | `Shift+F12` | Find all usages of symbol | |
| 743 | +| **Code Actions** | `Ctrl+.` | Quick fixes and refactorings | |
| 744 | +| **Rename Symbol** | `F2` | Rename across entire project | |
| 745 | +| **Document Symbols** | `Ctrl+Shift+O` | Outline of current file | |
| 746 | +| **Workspace Symbols** | `Ctrl+Shift+T` | Search symbols across project | |
| 747 | +| **Format Document** | `Shift+Alt+F` | Auto-format code | |
| 748 | +| **Command Palette** | `Ctrl+Shift+P` | Access all commands | |
| 749 | +| **Jump Back** | `Alt+,` | Return to previous location | |
| 750 | + |
| 751 | +--- |
| 752 | + |
| 753 | +## Supported Languages |
| 754 | + |
| 755 | +`fac` can work with **any** language that has an LSP server. Here are popular ones: |
| 756 | + |
| 757 | +| Language | Server | Installation | |
| 758 | +|----------|--------|--------------| |
| 759 | +| Python | `pylsp` | `pip install python-lsp-server` | |
| 760 | +| JavaScript/TypeScript | `typescript-language-server` | `npm install -g typescript-language-server` | |
| 761 | +| Rust | `rust-analyzer` | `rustup component add rust-analyzer` | |
| 762 | +| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` | |
| 763 | +| C/C++ | `clangd` | `brew install llvm` or `apt install clangd` | |
| 764 | +| Java | `jdtls` | Download from Eclipse | |
| 765 | +| Ruby | `solargraph` | `gem install solargraph` | |
| 766 | +| PHP | `intelephense` | `npm install -g intelephense` | |
| 767 | +| Bash | `bash-language-server` | `npm install -g bash-language-server` | |
| 768 | +| Fortran | `fortls` | `pip install fortls` | |
| 769 | +| Lua | `lua-language-server` | Download from GitHub | |
| 770 | +| HTML/CSS | `vscode-html-languageserver` | `npm install -g vscode-html-languageserver-bin` | |
| 771 | + |
| 772 | +For more language servers, visit: https://microsoft.github.io/language-server-protocol/implementors/servers/ |
| 773 | + |
| 774 | +--- |
| 775 | + |
| 776 | +## What's Next? |
| 777 | + |
| 778 | +Now that you understand LSP in `fac`: |
| 779 | + |
| 780 | +1. **Install language servers** for your languages |
| 781 | +2. **Practice the keybindings** - they'll become second nature |
| 782 | +3. **Explore your codebase** with `Ctrl+Shift+T` and `F12` |
| 783 | +4. **Let LSP catch errors** before you run your code |
| 784 | +5. **Refactor confidently** with `F2` and `Ctrl+.` |
| 785 | + |
| 786 | +Welcome to IDE-level coding in the terminal! 🚀 |
