lsp-inspect

Files (1)

• SKILL.md

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-inspect

Full code quality audit for a file, package, or directory. Combines LSP batch
analysis (`blast_radius`) with targeted per-symbol checks and LLM-driven
heuristic analysis. Produces a severity-tiered findings report with confidence
tiers and fix suggestions.

## When to Use

- Auditing a package before a release or major refactor
- Finding dead code, untested exports, and error handling gaps in unfamiliar code
- Reviewing code quality of an external codebase for contribution opportunities
- Pre-merge quality gate on a set of changed files
- Batch inspection of an entire directory with ranked output
- Comparing branch changes against main to find newly introduced issues

## Input

```
/lsp-inspect <target> [--checks <type1>,<type2>] [--json] [--top N] [--diff]
```

**Target** can be:
- A file path: `/lsp-inspect src/handlers/auth.go`
- A directory/package: `/lsp-inspect internal/runnables/`
- Multiple targets: `/lsp-inspect pkg/a.go pkg/b.go`

**Directory detection:** When target is a directory, walk all `.go`, `.ts`, `.py`
files in it recursively. Produce a ranked report: "Top N findings sorted by
severity then blast radius."

**Flags:**
- `--checks <type1>,<type2>`: only run listed check types (default: all applicable)
- `--json`: emit structured JSON instead of markdown
- `--top N`: Maximum findings to report (default 20). Only applies to directory/batch mode.
- `--diff`: Only inspect files changed vs main branch. Filter findings to lines within the diff ranges. Output header: "New issues introduced by this branch."

## Check Taxonomy

| Check | What it finds | LSP strategy |
|-------|--------------|--------------|
| `dead_symbol` | Exported symbol with zero references | Tier 1A: `blast_radius` batch; Tier 1B: `find_references` per-symbol |
| `test_coverage` | Exported symbol with no test callers | Tier 1A: `blast_radius` test_callers field |
| `silent_failure` | Error/exception suppressed without re-raise or logging | Read code, identify bare `except:`, empty `if err != nil {}`, swallowed returns |
| `error_wrapping` | Error returned/raised without context | Read code, identify `return err` without `fmt.Errorf` wrapping or `raise` without `from` |
| `coverage_gap` | Unhandled input, error path, or code branch | Read code, identify switch/match without default, unchecked type assertions |
| `doc_drift` | Docstring/comment that doesn't match the actual signature | Compare `inspect_symbol` hover text against source |
| `panic_not_recovered` | Unhandled crash in a goroutine or async context | Read code, identify `go func()` without recover, unguarded `.unwrap()` |
| `context_propagation` | Function receives context but creates a fresh root for callees | Read code, identify `context.Background()` in functions with `ctx` parameter |
| `unrecovered_concurrent_entry` | Concurrent entry point without recovery | Read code, identify goroutines/threads/tasks without try-catch or recover |
| `unchecked_shared_state` | Type assertion or cast on concurrent data structure without safety check | Read code, identify bare `.(*Type)` on sync.Map, unchecked casts on ConcurrentHashMap |
| `channel_never_closed` | Channel or queue created but never closed in the same package | Read code + grep, find creation sites without matching close/shutdown |
| `shared_field_without_sync` | Field accessed from concurrent contexts without synchronization | `blast_radius` (sync_guarded) + `find_callers` (cross_concurrent) |

## Execution

### Step 0: Initialize and verify workspace

```
mcp__lsp__start_lsp(root_dir="<repo_root>")
```

Open one file per package being audited:

```
mcp__lsp__open_document(file_path="<target_file>", language_id="<lang>")
```

**Warm-up check (mandatory):** Pick one symbol you know is actively used.
Call `find_references` on it. If it returns `[]`, wait 3-5 seconds and retry.
Do not proceed until a known-active symbol returns >= 1 reference.

### Step 0.5: Diff mode file selection

When `--diff` is set:
1. Run `git diff --name-only main` to get changed files
2. Run `git diff main` to get line-level change ranges
3. Use only changed files as inspection targets
4. After Step 3, filter findings: keep only those whose File:Line falls within
   a changed line range from the diff
5. Prepend output with: '## New issues introduced by this branch'

### Step 1: Batch analysis (Tier 1A)

Call `blast_radius` once per file in the target:

```
mcp__lsp__blast_radius(changed_files=["/abs/path/file.go"], include_transitive=false)
```

This returns all exported symbols with:
- `non_test_callers`: count of production code references
- `test_callers`: count of test file references

Classify immediately:
- `non_test_callers == 0 AND test_callers == 0` -> dead symbol candidate (confidence: verified)
- `non_test_callers == 0 AND test_callers > 0` -> test-only (may be dead, confidence: suspected)
- `non_test_callers > 0 AND test_callers == 0` -> untested export (confidence: verified)

If `blast_radius` fails or is unavailable, fall back to Tier 1B
(`find_references` per-symbol) for `dead_symbol` checks.

### Step 2: Heuristic checks (LLM-driven)

Read the source code of each file (use offset/limit for files over 500 lines).
Apply the following checks by reading and reasoning about the code:

**silent_failure:** Look for:
- Go: `if err != nil { return }` (no error returned), bare `_ = fn()`
- Python: bare `except:` or `except Exception: pass`
- TypeScript: empty `.catch(() => {})`, `try {} catch(e) {}`
- Rust: `.unwrap_or_default()` on fallible ops that should propagate

**error_wrapping:** Look for:
- Go: `return err` without `fmt.Errorf("context: %w", err)`
- Python: `raise ValueError(str(e))` without `from e`
- TypeScript: `throw e` without wrapping in a contextual error

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp