Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/lsp/README.md

Raw
Rendered preview
lsp

lsp

Navigate declarations, discover symbols, inspect one-hop calls through installed Go, TypeScript, C++ language servers.

Use in Pi

Ask Pi: Use lsp definition for main.go at line 8, column 12. Operations: definition | references | hover | type_definition | implementations | document_symbols | workspace_symbols | incoming_calls | outgoing_calls. Document symbols require file, no position. Workspace symbols require query (≤256 characters), plus server when profile selection is ambiguous; no file or position required. Example: Use lsp workspace_symbols with query Caller and server clangd. Call operations prepare targets first; ambiguous results expose candidate names, locations, opaque selection tokens. Repeat the same operation/file/position/workspace/server with a token to select a target; either call direction can use the selection. Tokens expire after five minutes, source/config/root/session changes, or bounded-cache eviction; rejected selections require a fresh query. Calls return one hop, never a recursive or runtime call graph. Successful preparation with no relationships returns ok; no prepared target returns no_result with readiness unknown. Lines and columns start at 1; columns count Unicode scalars, not bytes or UTF-16 units. References include declarations.

Install language servers yourself, place executables on PATH: gopls | typescript-language-server --stdio | clangd. Profiles: gopls (.go), typescript-language-server (.ts), clangd (.cpp, .cc, .cxx, .hpp). TypeScript language server also needs a TypeScript SDK containing tsserver.js; TypeScript 7 native-only distributions do not supply it. TypeScript requests use the semantic server, not the partial-semantic syntax fallback. Windows npm shims launch through Pi's Node runtime, which must satisfy the installed server's Node requirement. Operations depend on actual advertised capabilities; unsupported queries fail explicitly, never use approximate fallbacks. Workspace symbols may retain unresolved locations when the server provides no supported resolver. Queries use packaged, reviewed registry/provenance, never upstream catalogs. No server auto-install, command execution, workspace edits, completion, or editor-buffer integration. Native servers run with your OS permissions, may read workspace/dependency files, create indexes/caches, or invoke their own workers. The client denies server-requested workspace edits and command execution; this is not an OS sandbox. Automatic Go dependency downloads/toolchain upgrades are disabled.

File paths resolve from Pi cwd. Root discovery uses packaged profile markers inside cwd; multiple roots require explicit workspace. Use server to select a profile explicitly; missing executables name the required command. Explicit workspace must contain the file. At most two workspace/config sessions, one active query per workspace. Restart Pi session to release idle workspaces or observation budgets.

Whole-call timeout defaults to 15 seconds, configurable per call as timeout_ms (100–60000). max_results defaults to 50 (1–100); max_bytes defaults to 16384 (2048–32768). Resource exhaustion fails explicitly; query cancellation closes its server session. Sessions have bounded protocol traffic; large/long-lived sessions may require retry.

Disk snapshots synchronize managed files and bounded observed sibling source/config files before requests. Observation is bounded to eight directories, 256 entries per directory, 128 source files/4 MiB; individual files ≤512 KiB. Unopened dependencies also rely on gopls 0.24's experimental filesystem watcher, not an exhaustive client scan. Workspace/index freshness, readiness, server completeness remain unknown. Source snippets/ranges use current disk snapshots, not server-revision-verified evidence. no_result means the server returned nothing, not proven semantic absence. Tool truncation is explicit; silent server limits remain unknown.

Installation

Timeout setting precedence: env → trusted project → user → default. Untrusted project settings are ignored; invalid selected values fail queries.

Reference

Setting names

Setting Environment
lsp.timeoutMs PI_LSP_TIMEOUT_MS

Setting values

Setting Default Valid values Purpose
lsp.timeoutMs 15000 Integer 100–60000 Query timeout: Whole-call deadline in milliseconds; invalid configuration fails the query.
<img src="assets/banner.svg" alt="lsp" height="70">

# lsp

Navigate declarations, discover symbols, inspect one-hop calls through installed Go, TypeScript, C++ language servers.

## Use in Pi

Ask Pi: `Use lsp definition for main.go at line 8, column 12.`
Operations: `definition` | `references` | `hover` | `type_definition` | `implementations` | `document_symbols` | `workspace_symbols` | `incoming_calls` | `outgoing_calls`.
Document symbols require `file`, no position.
Workspace symbols require `query` (≤256 characters), plus `server` when profile selection is ambiguous; no file or position required.
Example: `Use lsp workspace_symbols with query Caller and server clangd.`
Call operations prepare targets first; ambiguous results expose candidate names, locations, opaque `selection` tokens.
Repeat the same operation/file/position/workspace/server with a token to select a target; either call direction can use the selection.
Tokens expire after five minutes, source/config/root/session changes, or bounded-cache eviction; rejected selections require a fresh query.
Calls return one hop, never a recursive or runtime call graph.
Successful preparation with no relationships returns `ok`; no prepared target returns `no_result` with readiness unknown.
Lines and columns start at 1; columns count Unicode scalars, not bytes or UTF-16 units.
References include declarations.

Install language servers yourself, place executables on PATH: `gopls` | `typescript-language-server --stdio` | `clangd`.
Profiles: `gopls` (`.go`), `typescript-language-server` (`.ts`), `clangd` (`.cpp`, `.cc`, `.cxx`, `.hpp`).
TypeScript language server also needs a TypeScript SDK containing `tsserver.js`; TypeScript 7 native-only distributions do not supply it.
TypeScript requests use the semantic server, not the partial-semantic syntax fallback.
Windows npm shims launch through Pi's Node runtime, which must satisfy the installed server's Node requirement.
Operations depend on actual advertised capabilities; unsupported queries fail explicitly, never use approximate fallbacks.
Workspace symbols may retain unresolved locations when the server provides no supported resolver.
Queries use packaged, reviewed [registry/provenance](registry/servers.json), never upstream catalogs.
No server auto-install, command execution, workspace edits, completion, or editor-buffer integration.
Native servers run with your OS permissions, may read workspace/dependency files, create indexes/caches, or invoke their own workers.
The client denies server-requested workspace edits and command execution; this is not an OS sandbox.
Automatic Go dependency downloads/toolchain upgrades are disabled.

File paths resolve from Pi cwd.
Root discovery uses packaged profile markers inside cwd; multiple roots require explicit `workspace`.
Use `server` to select a profile explicitly; missing executables name the required command.
Explicit workspace must contain the file.
At most two workspace/config sessions, one active query per workspace.
Restart Pi session to release idle workspaces or observation budgets.

Whole-call timeout defaults to 15 seconds, configurable per call as `timeout_ms` (100–60000).
`max_results` defaults to 50 (1–100); `max_bytes` defaults to 16384 (2048–32768).
Resource exhaustion fails explicitly; query cancellation closes its server session.
Sessions have bounded protocol traffic; large/long-lived sessions may require retry.

Disk snapshots synchronize managed files and bounded observed sibling source/config files before requests.
Observation is bounded to eight directories, 256 entries per directory, 128 source files/4 MiB; individual files ≤512 KiB.
Unopened dependencies also rely on gopls 0.24's experimental filesystem watcher, not an exhaustive client scan.
Workspace/index freshness, readiness, server completeness remain unknown.
Source snippets/ranges use current disk snapshots, not server-revision-verified evidence.
`no_result` means the server returned nothing, not proven semantic absence.
Tool truncation is explicit; silent server limits remain unknown.

[Installation](../../README.md#install)

Timeout setting precedence: env → trusted project → user → default.
Untrusted project settings are ignored; invalid selected values fail queries.

## Reference

<!-- config:start -->
### Setting names

| Setting | Environment |
| --- | --- |
| `lsp.timeoutMs` | `PI_LSP_TIMEOUT_MS` |

#### Setting values

| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `lsp.timeoutMs` | `15000` | Integer 100–60000 | Query timeout: Whole-call deadline in milliseconds; invalid configuration fails the query. |
<!-- config:end -->