/lsp-code-analysis

name: lsp-code-analysis
description: Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring.
license: LICENSE

LSP Code Analysis

IMPORTANT: PREREQUISITE

To use this skill, you **MUST** follow these steps:

1. **Check for updates**: Run the [update script](scripts/update.sh) to ensure you are using the latest version of the tool. 2. **Verify project support**: Run `lsp server start <project_path>` to start the LSP server and confirm the project is supported.

**IF YOU DO NOT PERFORM THESE STEPS, YOU ARE NOT ALLOWED TO USE THIS SKILL.**

Abstract

This document specifies the operational requirements and best practices for the `lsp-code-analysis` skill. It provides a semantic interface to codebase navigation, analysis and refactoring via the Language Server Protocol (LSP).

Overview

You are provided with `lsp` CLI tool for semantic code navigation and analysis. It SHOULD be preferred over `read` or `grep` for most code understanding tasks.

Usages:

• **Semantic navigation**: Jump to definitions, find references, locate implementations - understands code structure, not just text patterns.
• **Language-aware**: Distinguishes between variables, functions, classes, types - eliminates false positives from text search.
• **Cross-file intelligence**: Trace dependencies, refactor safely across entire codebase - knows what imports what.
• **Type-aware**: Get precise type information, signatures, documentation - without reading implementation code.

Tool Selection

**Guideline**: You SHOULD prioritize LSP commands for code navigation and analysis. Agents MAY use `read` or `grep` ONLY when semantic analysis is not applicable (e.g., searching for comments or literal strings).

| Task | Traditional Tool | Recommended LSP Command | | ------------------- | ---------------- | ----------------------------------------------- | | **Find Definition** | `grep`, `read` | [`definition`](#definition-navigate-to-source) | | **Find Usages** | `grep -r` | [`reference`](#reference-find-all-usages) | | **Understand File** | `read` | [`outline`](#outline-file-structure) | | **View Docs/Types** | `read` | [`doc`](#doc-get-documentation) | | **Refactor** | `sed` | See [Refactoring Guide](references/refactor.md) |

Commands

All commands support `-h` or `--help`.

Locating Symbols

Most commands use a unified locating syntax via the `--scope` and `--find` options.

**Arguments**: `<file_path>`

**Options**:

• `--scope`: Narrow search to a symbol body or line range.
• `--find`: Text pattern to find within the scope.

**Scope Formats**:

• `<line>`: Single line number (e.g., `42`).
• `<start>,<end>`: Line range (e.g., `10,20`). Use `0` for end to mean till EOF (e.g., `10,0`).
• `<symbol_path>`: Symbol path with dots (e.g., `MyClass.my_method`).

**Find Pattern (`--find`)**:

The `--find` option narrows the target to a **text pattern within the selected scope**:

• The scope is determined by `--scope` (line/range/symbol). If no `--scope` is given, the entire file is the scope.
• Pattern matching is **whitespace-insensitive**: differences in spaces, tabs, and newlines are ignored.
• You MAY include the cursor marker `<|>` inside the pattern to specify the **exact position of interest** within the match (for example, on a variable name, keyword, or operator).
• If `--find` is omitted, the command uses the start of the scope (or a tool-specific default) as the navigation target.

**Cursor Marker (`<|>`)**:

The `<|>` marker indicates the exact position for symbol resolution. It represents the character immediately to its right. Use it within the find pattern to point to a specific element (e.g., `user.<|>name` to target the `name` property).

**Examples**:

• `lsp doc foo.py --find "self.<|>"` - Find `self.` in entire file, position at the character after the dot (typically for completion or member access)
• `lsp doc foo.py --scope 42 --find "return <|>result"` - Find `return result` on line 42, position at `r` of `result`
• `lsp doc foo.py --scope 10,20 --find "if <|>condition"` - Find `if condition` in lines 10-20, position at `c` of `condition`
• `lsp doc foo.py --scope MyClass.my_method --find "self.<|>"` - Find `self.` within `MyClass.my_method`, position after the dot
• `lsp doc foo.py --scope MyClass` - Target the `MyClass` symbol directly

**Guideline for Scope vs. Find**:

• Use `--scope <symbol_path>` (e.g., `--scope MyClass`, `--scope MyClass.my_method`) to target **classes, functions, or methods**. This is the most robust and preferred way to target symbol.
• Use `--find` (often combined with `--scope`) to target variables or specific positions. Use this when the target is not a uniquely named symbol or when you need to pinpoint a specific usage within a code block.

Agents MAY use `lsp locate <file_path> --scope <scope> --find <find>` to verify if the target exists in the file and view its context before running other commands.

# Verify location exists
lsp locate main.py --scope 42 --find "<|>process_data"

Pagination

Use pagination for large result sets like `reference` or `search`.

• `--pagination-id <ID>`: (Required) Unique session ID for consistent paging.
• `--max-items <N>`: Page size.
• `--start-index <N>`: Offset (0-based).

**Example**:

# Page 1
lsp search "User" --max-items 20 --pagination-id "task_123"

# Page 2
lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"

**Guideline**: Use pagination with a unique ID for common symbols to fetch results in manageable chunks. Increment `--start-index` using the same ID to browse.

Outline: File Structure

Get hierarchical symbol structure without reading implementation.

# Ge