149 lines
5.8 KiB
Markdown
149 lines
5.8 KiB
Markdown
---
|
|
name: lsp-cli
|
|
description: >-
|
|
MANDATORY for Chromium C/C++ semantic analysis and compiler diagnostics.
|
|
Activate before exact symbol, definition, caller, implementation,
|
|
inheritance, or call-stack analysis, and after every C/C++ edit. Diagnostics
|
|
for every modified C/C++ file must report zero errors before a build; report
|
|
and stop when the CLI, session, or diagnostics are unavailable.
|
|
---
|
|
|
|
# lsp-cli (C++ MCP CLI)
|
|
|
|
lsp-cli.py is a lightweight CLI front-end to the C++ MCP server. It connects
|
|
using the session cached in `.lsp-cli.json`. Use it for precise, index-backed
|
|
C++ symbol lookup in the large Chromium tree.
|
|
|
|
## Hard stops
|
|
|
|
Before semantic analysis or diagnostics, locate `lsp-cli.py` at the project
|
|
root or in this skill directory. If it is missing, report that exact condition
|
|
and STOP.
|
|
|
|
The cached `.lsp-cli.json` session and its endpoint must be usable. If the
|
|
file is missing, its endpoint is unavailable, or a CLI command exits non-zero,
|
|
report the command and complete failure output, then STOP. Do not guess an
|
|
endpoint, try an alternate endpoint, or create or replace a session cache
|
|
without a new user instruction.
|
|
|
|
**ALWAYS** On any other errors related to `lsp-cli.py` -- report to user and
|
|
stop, do not act on your own.
|
|
|
|
## Required diagnostic gate
|
|
|
|
After every C/C++ source or header edit, run diagnostics for every modified
|
|
file before starting a build:
|
|
|
|
```sh
|
|
./lsp-cli.py diagnostics path/to/modified/file1.cc path/to/modified/file2.h
|
|
```
|
|
|
|
Report all errors and warnings. Zero errors is required to proceed to a build.
|
|
If diagnostics report any error, cannot cover every modified file, or fail to
|
|
run, report the result and STOP. Do not build, retry, or substitute another
|
|
compiler-diagnostic command until the user gives a new instruction.
|
|
|
|
## How to get more information
|
|
|
|
```sh
|
|
./lsp-cli.py --help # to get available arguments and examples
|
|
```
|
|
|
|
`--build-directory` should be inherited from running server (no need to specify explicitly in normal usage)
|
|
|
|
## Typical usage examples
|
|
|
|
All commands run from the project root (`/media/vptyp/images1/webos-ose/chromium/src`).
|
|
The server resolves the default build directory from the project-root
|
|
`compile_commands.json`, so `--build-directory` is only needed when you want a
|
|
different build dir than the default.
|
|
|
|
### 1. Orient: project layout and index state
|
|
|
|
```sh
|
|
./lsp-cli.py project # build dirs, compilation flags + compilation database the server resolved
|
|
./lsp-cli.py index # snapshot of clangd indexing progress
|
|
./lsp-cli.py index --wait-timeout 300 # block (up to 300s) until clangd reports done
|
|
```
|
|
|
|
Note: while clangd is *loading* an existing on-disk index (not building),
|
|
`index` may report `progress_percentage: 0.0` even though queries already
|
|
work. Trust a successful `search`/`analyze` over the percentage during load.
|
|
|
|
### 2. Find symbols
|
|
|
|
Search uses clangd fuzzy matching against the *qualified* name, so scoped
|
|
queries work:
|
|
|
|
```sh
|
|
./lsp-cli.py search "InfoBar::Show" # scoped query -> infobars::InfoBar::Show
|
|
./lsp-cli.py search "Show" --kind Method # bare name, restrict to methods
|
|
./lsp-cli.py search "Buffer" --kind Class Struct # find types only
|
|
./lsp-cli.py search "" --files chrome/browser/extensions/api/tabs/tabs_api.cc # list a file's symbols
|
|
./lsp-cli.py search "std::" --include-external # include system/library symbols
|
|
./lsp-cli.py search "InfoBar" --max-results 20 # cap result count
|
|
```
|
|
|
|
Kinds are PascalCase, one or more: `Class Struct Function Method Field
|
|
Constructor Interface Module Namespace Enum` (see `search --help`).
|
|
|
|
### 3. Deep analysis of one symbol
|
|
|
|
`analyze` returns definition, hover, usage examples, and (when applicable)
|
|
inheritance + call hierarchy. It auto-selects the analyses that fit the symbol
|
|
kind — no flags for inheritance/call hierarchy.
|
|
|
|
```sh
|
|
./lsp-cli.py analyze "InfoBar::Show" # full context
|
|
./lsp-cli.py analyze "InfoBar::Show" --max-examples 5 # cap usage examples
|
|
./lsp-cli.py analyze "foo" --location-hint path/to/file.cc:42:15 # disambiguate an overload
|
|
```
|
|
|
|
`--location-hint` is `FILE:LINE:COL` and resolves a specific overload when the
|
|
name alone is ambiguous.
|
|
|
|
### 4. Diagnostic gate (run after every C/C++ edit)
|
|
|
|
Accepts one or more files; run it for every modified source/header before a
|
|
build and require zero errors:
|
|
|
|
```sh
|
|
./lsp-cli.py diagnostics chrome/browser/extensions/api/tabs/tabs_api.cc
|
|
./lsp-cli.py diagnostics a.cc b.h include/c.h # multi-file in one call
|
|
./lsp-cli.py diagnostics file.cc --wait-timeout 60 # give clangd longer to parse
|
|
```
|
|
|
|
If a file is still being reparsed, the first call after idle can be slow while
|
|
clangd pages its index back in from swap; subsequent calls are fast. Never hide
|
|
with grep timed_out or you may receive false results
|
|
|
|
### 5. Output formats (apply to every command)
|
|
|
|
```sh
|
|
./lsp-cli.py --format json search "Show" > show.json # tool result as JSON, for scripting
|
|
./lsp-cli.py --format raw diagnostics file.cc # full JSON-RPC response, for debugging
|
|
```
|
|
|
|
### Flag placement (important)
|
|
|
|
- Global flags go **before** the subcommand: `--format`, `--server-path`,
|
|
`--http-url`, `--config`, `--debug`, and the hidden `--attach-timeout`
|
|
(default 30s; raise it if the CLI times out attaching to a busy server).
|
|
- Subcommand flags go **after** the subcommand: `--wait-timeout`,
|
|
`--build-directory`, `--kind`, `--files`, `--max-examples`, `--location-hint`.
|
|
|
|
```sh
|
|
./lsp-cli.py --format json --attach-timeout 60 search "Show" --wait-timeout 120
|
|
# ^^^^^^^^^^^^^ global ^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^ subcommand
|
|
```
|
|
|
|
### Possible CLI locations
|
|
|
|
- Project root
|
|
- skill directory
|
|
|
|
## Why use lsp-cli.py
|
|
|
|
The clangd index resolves qualified names and overloads reliably for the active
|
|
build configuration, yielding exact definitions and call sites.
|