bitwisecook/lsp-client

Tcl LSP Client

Runs a standalone LSP client that starts the Tcl language server, exercises an LSP feature against a Tcl file, and prints human-readable results. Use this to verify server behavior after making changes.

Usage

Run from the project root (the git worktree directory):

python3 .claude/skills/lsp-client/lsp_client.py <subcommand> <args...>

The script auto-detects the tcl-lsp/ server directory. Override with --server-dir /path/to/tcl-lsp if needed.

Subcommands

| Subcommand | Arguments | What it does | |---|---|---| | semantic-tokens | <file.tcl> | Decode and display all semantic tokens with types | | diagnostics | <file.tcl> | Show warnings, errors, hints from the analyzer and optimizer | | format | <file.tcl> | Show formatting edits the server would apply | | hover | <file.tcl> <line> <col> | Show hover info at a 0-based position | | completion | <file.tcl> <line> <col> | Show completions at a 0-based position | | definition | <file.tcl> <line> <col> | Show go-to-definition locations | | references | <file.tcl> <line> <col> | Show all reference locations | | code-actions | <file.tcl> <l> <c> <el> <ec> | Show code actions in a 0-based range | | optimize | <file.tcl> | Show optimization suggestions and rewritten source | | symbols | <file.tcl> | Show document symbol hierarchy (procs, events, namespaces, variables) | | diagram | <file.tcl> | Extract control flow diagram data from compiler IR | | event-info | <EVENT_NAME> | Show iRules event registry metadata (no file needed) | | command-info | <COMMAND_NAME> | Show iRules command registry metadata (no file needed) | | context | <file.tcl> | Build context pack: diagnostics + symbols + event metadata | | all | <file.tcl> | Run semantic-tokens + diagnostics + symbols + format + optimize together | | bench | <file.tcl> [--iterations N] | Benchmark time-to-semantic-tokens with server timing breakdown | | logs | <file.tcl> [--timing-only] | Collect and display server logs and timing information |

All line/col arguments are 0-based, matching the LSP protocol.

Interpreting Output

Semantic Tokens

Each token shows line:col type "text":

  0:0  keyword      "set"
  0:4  string       "name"
  1:0  keyword      "puts"
  1:5  variable     "$name"

Token types: keyword, function, variable, string, comment, number, operator, parameter, namespace, regexp.

Diagnostics

  WARNING  W100  2:4-2:18  Unbraced expr in 'if' condition
  HINT     W302  5:0-5:12  catch without result variable
  INFO     O101  3:10-3:18  Fold constant expression

Optimizer suggestions (O100, O101, O102) appear as INFO-level diagnostics with QuickFix code actions in VS Code.

Optimizations

=== Optimizations (2 items) ===
  O101   2:10-2:18  Fold constant expression  →  "{3}"
  O102   3:8-3:27   Fold constant expr command substitution  →  "3"

=== Optimized Source ===
    set a 1
    set b 3
    ...

Shows each optimization and the fully rewritten source.

Symbols

=== Symbol Definitions (4 symbols) ===
  Event HTTP_REQUEST (line 1)
  Event HTTP_RESPONSE (line 15)
  Function my_proc (a b) (line 25)
    Variable result (line 26)

Hierarchical display of events, procs, namespaces, and variables.

Diagram Data

Shows events in canonical firing order with multiplicity and priority, procedures with parameters, and the full structured JSON for diagram generation.

Event Info

=== Event Info ===
  Event: HTTP_REQUEST
  Known: yes
  Deprecated: no
  Valid commands: 87
  Sample commands: HTTP::host, HTTP::path, HTTP::method, ...

Command Info

=== Command Info ===
  Command: HTTP::uri
  Summary: Returns or sets the HTTP URI
  Synopsis: HTTP::uri [<uri>]
  Valid in: HTTP_REQUEST, HTTP_RESPONSE, ...

Context Pack

Combined output for AI skill consumption:

=== Context Pack ===
  Dialect: f5-irules
  File: redirect.tcl
  Lines: 42

=== Diagnostics (2) ===
  WARNING W100 line 15: unbraced expression in expr
  WARNING W304 line 22: missing -- option terminator

=== Symbol Definitions (3) ===
  Event HTTP_REQUEST (line 1)
  Event HTTP_RESPONSE (line 15)
  Function my_proc (a b) (line 25)

=== Event Metadata (2 events, in source order) ===
  HTTP_REQUEST: known=yes, deprecated=no, validCommands=87
    sample: HTTP::host, HTTP::path, HTTP::method, HTTP::uri
  HTTP_RESPONSE: known=yes, deprecated=no, validCommands=45
    sample: HTTP::header, HTTP::status

Hover

Shows the markdown content the editor would display on hover.

Completions

Shows label, kind (Keyword, Function, Variable), and detail.

Bench

Measures wall-clock time from request to semantic token response, plus server-side timing breakdown from [timing] log entries:

=== Benchmark ===
  File: 09_long_code.tcl
  Lines: 540, Size: 15208 bytes
  Iterations: 3

  Iteration 1:
    Wall clock (request → response): 445.1ms
    Tokens: 1557
    Server timings:
      _build_full_chunk_caches: 1ms
      semantic_tokens_full: 200ms
      semanticTokens/full: 200ms
      workspace_state.update: 459ms

  After mid-file edit:
    Wall clock: 180.5ms
    Server timings:
      workspace_state.update: 150ms

Use --iterations N to run multiple open/close cycles for reliable medians. The edit benchmark simulates a mid-file change to measure incremental update performance.

Logs

Shows server stderr and window/logMessage notifications. Use --timing-only to filter to just [timing] entries for performance analysis.

When to Use

• After changing semantic token logic, verify tokens are correct
• After changing diagnostic checks, verify warnings appear
• After changing the formatter, verify edit output
• After changing the optimizer, verify suggestions and rewrites
• Quick smoke test with all on any example file
• Verify position-dependent features (hover, completion, definition) at specific cursor locations
• Use context to build rich LSP context for AI skill consumption
• Use diagram to extract structured flow data for Mermaid generation
• Use event-info / command-info to look up iRules registry metadata
• After performance changes, use bench to measure time-to-semantic-tokens
• Use logs --timing-only to see the server-side timing breakdown

Example Invocations

python3 .claude/skills/lsp-client/lsp_client.py semantic-tokens tcl-lsp/samples/for_screenshots/03-completions.tcl
python3 .claude/skills/lsp-client/lsp_client.py diagnostics tcl-lsp/editors/vscode/testFixture/diagnostics.tcl
python3 .claude/skills/lsp-client/lsp_client.py hover tcl-lsp/editors/vscode/testFixture/procs.tcl 1 6
python3 .claude/skills/lsp-client/lsp_client.py optimize tcl-lsp/samples/for_screenshots/22-optimiser-before.tcl
python3 .claude/skills/lsp-client/lsp_client.py symbols tcl-lsp/samples/for_screenshots/ai-scene.irul
python3 .claude/skills/lsp-client/lsp_client.py diagram tcl-lsp/samples/for_screenshots/ai-scene.irul
python3 .claude/skills/lsp-client/lsp_client.py event-info HTTP_REQUEST
python3 .claude/skills/lsp-client/lsp_client.py command-info HTTP::uri
python3 .claude/skills/lsp-client/lsp_client.py context tcl-lsp/samples/for_screenshots/ai-scene.irul
python3 .claude/skills/lsp-client/lsp_client.py all tcl-lsp/samples/for_screenshots/03-completions.tcl
python3 .claude/skills/lsp-client/lsp_client.py bench tcl-lsp/samples/tcl/09_long_code.tcl --iterations 3
python3 .claude/skills/lsp-client/lsp_client.py logs tcl-lsp/samples/tcl/09_long_code.tcl --timing-only

$ARGUMENTS