lsp-hover-testing

name	lsp-hover-testing
description	Automated LSP hover validation for Dingo transpiler. Use when testing hover functionality, validating position mappings, checking for hover drift, or debugging LSP issues after sourcemap changes.
allowed-tools	Read, Grep, Glob, Bash, Write, Edit

LSP Hover Testing Skill

Automated headless testing of LSP hover functionality for the Dingo transpiler. Replaces manual VS Code hover checks with reproducible, CI-compatible tests.

When to Use This Skill

• After making changes to sourcemap/position tracking code
• When debugging hover issues reported by users
• To validate that column/line mappings work correctly
• Before committing changes to pkg/lsp/, pkg/sourcemap/, or pkg/transpiler/
• To create regression tests for hover functionality

Quick Start

# Build the tools first
go build -o dingo ./cmd/dingo
go build -o editors/vscode/server/bin/dingo-lsp ./cmd/dingo-lsp
go build -o lsp-hovercheck ./cmd/lsp-hovercheck

# Run hover tests
./lsp-hovercheck --spec "ai-docs/hover-specs/*.yaml"

# Verbose output for debugging
./lsp-hovercheck --spec ai-docs/hover-specs/http_handler.yaml --verbose

Spec File Format

Create YAML specs in ai-docs/hover-specs/:

file: examples/01_error_propagation/http_handler.dingo

cases:
  - id: 1
    line: 55                    # 1-based line number
    token: userID               # Token to hover on
    occurrence: 1               # Which occurrence (default: 1)
    description: "LHS variable"
    expect:
      contains: "var userID string"      # Must contain substring
      # OR
      containsAny:                        # Any of these
        - "var userID"
        - "userID string"
      # OR
      allowAny: true                      # Accept any result (skip assertion)

Assertion Types

Type	Description	Example
contains	Must contain substring	contains: "func foo"
containsAny	Any of listed substrings	containsAny: ["func", "method"]
notContains	Must not contain	notContains: "error"
allowAny	Skip assertion, just record	allowAny: true

Output Format

http_handler.yaml:
------------------------------------------------------------
1: works
2: works
3: expected "var r", got "func extractUserID..."
4: works

============================================================
Total: 3 passed, 1 failed

Creating New Test Specs

Step 1: Identify test positions

# Show line numbers
sed -n '50,70p' examples/01_error_propagation/http_handler.dingo | nl -ba

Step 2: Create spec file

cat > ai-docs/hover-specs/my_example.yaml << 'EOF'
file: examples/my_example/file.dingo

cases:
  - id: 1
    line: 10
    token: myFunction
    description: "Function name hover"
    expect:
      contains: "func myFunction"
EOF

Step 3: Run and iterate

./lsp-hovercheck --spec ai-docs/hover-specs/my_example.yaml --verbose

Debugging Failed Tests

When a test fails, check:

1. Column position: Is the token found at the right column?
2. Tab handling: Lines starting with tabs may have offset issues
3. Transformed lines: Error prop lines map to different Go positions
4. LSP readiness: Increase --retries if hover returns empty

Verbose debug output

./lsp-hovercheck --spec ai-docs/hover-specs/http_handler.yaml --verbose

Shows:

• Exact LSP request/response JSON
• Computed column positions
• Hover content returned

Known Limitations

VS Code vs Automated Differences

The automated test may show different results than VS Code due to:

• Tab character handling differences
• LSP initialization timing
• VS Code extension preprocessing

Current Behavior (2025-12-14)

Position Type	Automated Result	VS Code Result
Function names	Works	Works
Function arguments	Works	Shows function sig (bug)
LHS variables	Empty	Shows temp var (bug)

File Locations

File	Purpose
cmd/lsp-hovercheck/	Hover check tool source
ai-docs/hover-specs/	Test specification files
editors/vscode/server/bin/dingo-lsp	LSP server binary

CI Integration

Add to your CI pipeline:

- name: Build tools
  run: |
    go build -o dingo ./cmd/dingo
    go build -o editors/vscode/server/bin/dingo-lsp ./cmd/dingo-lsp
    go build -o lsp-hovercheck ./cmd/lsp-hovercheck

- name: Run hover tests
  run: ./lsp-hovercheck --spec "ai-docs/hover-specs/*.yaml"

Related Files

• Spec format reference
• Debugging guide