pi-lens-lsp-navigation · diff
git:20260711.a8583f1 to git:20260815.4cc6eed
22 added, 22 removed. Audit A to A.
---
name: pi-lens-lsp-navigation
description: Navigate code with IDE features and run proactive LSP diagnostics on files/folders/batches. Use as PRIMARY for code intelligence and type/error checks.
---
# LSP Navigation and Diagnostics
Use `lsp_navigation` as **PRIMARY** for code intelligence. Use `lsp_diagnostics` as **PRIMARY** for proactive type/error checks. Do NOT use grep/glob/ast-grep first for code intelligence.
## Diagnostics
Use `lsp_diagnostics` before builds/tests or after touching several files:
| Need | Tool call |
|---|---|
- | Check one file | `lsp_diagnostics({ filePath: "src/file.ts" })` |
- | Check a folder | `lsp_diagnostics({ filePath: "src/", severity: "error" })` |
- | Check exact touched files | `lsp_diagnostics({ filePaths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
- | Slow server (Rust, Java) | `lsp_diagnostics({ filePaths: files, waitMs: 2000 })` |
- | Include warnings | `lsp_diagnostics({ filePaths: files, severity: "all" })` |
+ | Check one file | `lsp_diagnostics({ path: "src/file.ts" })` |
+ | Check a folder | `lsp_diagnostics({ path: "src/", severity: "error" })` |
+ | Check exact touched files | `lsp_diagnostics({ paths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
+ | Slow server (Rust, Java) | `lsp_diagnostics({ paths: files, waitMs: 2000 })` |
+ | Include warnings | `lsp_diagnostics({ paths: files, severity: "all" })` |
- Prefer explicit `filePaths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
+ Prefer explicit `paths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
## Navigation (Code Intelligence)
| Question | Operation | Parameters |
|---|---|---|
- | Where is this defined? | `definition` | filePath, line, character |
- | Where is this symbol's *type* defined? | `typeDefinition` | filePath, line, character |
- | Where is this declared (vs defined)? | `declaration` | filePath, line, character |
- | Find all usages | `references` | filePath, line, character |
- | What type is this? | `hover` | filePath, line, character |
- | Call signature | `signatureHelp` | filePath, line, character (at arg position) |
- | Symbols in this file | `documentSymbol` | filePath |
- | Find symbol across project | `workspaceSymbol` | query + filePath (strongly recommended) |
- | Quick fixes available | `codeAction` | filePath, line, character, endLine, endCharacter |
- | Rename symbol safely | `rename` | filePath, line, character, newName |
- | Who implements this? | `implementation` | filePath, line, character |
- | Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | filePath, line, character |
- | What does this call? | `prepareCallHierarchy` → `outgoingCalls` | filePath, line, character |
- | What commands does the server offer? | `capabilities` | (optional filePath) — lists advertised commands |
+ | Where is this defined? | `definition` | path, line, character |
+ | Where is this symbol's *type* defined? | `typeDefinition` | path, line, character |
+ | Where is this declared (vs defined)? | `declaration` | path, line, character |
+ | Find all usages | `references` | path, line, character |
+ | What type is this? | `hover` | path, line, character |
+ | Call signature | `signatureHelp` | path, line, character (at arg position) |
+ | Symbols in this file | `documentSymbol` | path |
+ | Find symbol across project | `workspaceSymbol` | query + path (strongly recommended) |
+ | Quick fixes available | `codeAction` | path, line, character, endLine, endCharacter |
+ | Rename symbol safely | `rename` | path, line, character, newName |
+ | Who implements this? | `implementation` | path, line, character |
+ | Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | path, line, character |
+ | What does this call? | `prepareCallHierarchy` → `outgoingCalls` | path, line, character |
+ | What commands does the server offer? | `capabilities` | (optional path) — lists advertised commands |
| Run a server command (e.g. organize imports) | `executeCommand` | command (+ commandArguments); dry-run unless `apply:true` |
## Call Hierarchy Pattern
```
// Step 1
- lsp_navigation(operation="prepareCallHierarchy", filePath="src/api.ts", line=42, character=10)
+ lsp_navigation(operation="prepareCallHierarchy", path="src/api.ts", line=42, character=10)
// → returns callHierarchyItem
// Step 2
lsp_navigation(operation="incomingCalls", callHierarchyItem=<item from step 1>)
lsp_navigation(operation="outgoingCalls", callHierarchyItem=<item from step 1>)
```
## Operational Notes
- **`definition` returns nothing?** The file may not be open/indexed yet. Read it first, then retry.
- - **`workspaceSymbol` empty?** Always pass `filePath`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
+ - **`workspaceSymbol` empty?** Always pass `path`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
- **`references`** — query from the *definition site* for full cross-file coverage; usage-site queries can be partial.
- **`signatureHelp`** — only valid at call-site argument positions; declaration positions return empty.
- **`workspaceDiagnostics`** — tracked push snapshot only, not an active check. Use `lsp_diagnostics` when you need fresh results.
- **`codeAction`** — distinguish `quickfix` from generic refactors ("Move to new file"). Generic refactors are not error fixes.
- **`prepareCallHierarchy`** — server-capability dependent; if unsupported, skip incoming/outgoing calls.
## When NOT to Use LSP Navigation
| Task | Use Instead |
|---|---|
| Find patterns (`console.log`) | `ast_grep_search` |
| Find text / TODOs | `grep` |
| Find files by name | `glob` |
| Read file content | `read` |
## Golden Rule
**Code intelligence → `lsp_navigation` first. Type/error validation → `lsp_diagnostics` first. Text/pattern search → grep/ast-grep.**