Lsp Inspect

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

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

coverage_gap: Look for:

• Switch/match without exhaustive cases or default branch
• Unchecked type assertions (v := x.(Type) vs v, ok := x.(Type))
• Missing nil/null checks before dereference after fallible calls

doc_drift: For exported functions, compare:

• Parameter names in docstring vs actual signature
• Return type described in doc vs actual return
• Use inspect_symbol hover text to cross-reference

panic_not_recovered: Look for:

• Go: go func() { ... }() without defer recover()
• Rust: .unwrap() or .expect() in non-test, non-main code
• Python: bare thread creation without exception handling

context_propagation: Look for:

• Functions that accept ctx context.Context but call context.Background() or context.TODO() internally

unrecovered_concurrent_entry: Detect concurrent entry points without recovery. Language-specific patterns (check by language family):

• Go: go func() { ... }() where the function body has no defer func() { if r := recover() pattern. Weight: library transport code (error severity), application code with middleware protection (info).
• Java/Kotlin/Scala: new Thread(...) or ExecutorService.submit(...) without try-catch wrapping the Runnable body, and no UncaughtExceptionHandler set on the thread.
• C#: Task.Run(...) or new Thread(...) without try-catch in the delegate body.
• C/C++: pthread_create or std::thread without exception handling in the thread function.
• Rust: std::thread::spawn without catch_unwind in the closure. Also flag .unwrap() inside spawned threads (panics kill only that thread but lose the error).
• Swift: DispatchQueue.async or Task { } without do-catch.
• Python: threading.Thread(target=...) without try-except in the target function. asyncio.create_task() without error handling on the awaited result.
• TypeScript/JavaScript: new Worker() without onerror or error event handler. Promise constructor without .catch() on the chain.
• Zig: try std.Thread.spawn without error handling on the spawned function.
• Elixir/Erlang/Gleam: Skip (actor model with supervisors; unrecovered processes are by design).
• Lua/Bash/SQL: Skip (no concurrency primitives).

unchecked_shared_state: Detect unsafe type operations on concurrent data structures:

• Go: sync.Map .Load(), .LoadOrStore(), or .LoadAndDelete() followed by a bare type assertion actual.(*Type) without the , ok pattern. The safe pattern is v, ok := actual.(*Type).
• Java: ConcurrentHashMap.get() with unchecked cast and no instanceof guard.
• C#: ConcurrentDictionary value retrieval with unchecked cast.
• Other languages: skip (dynamic typing or type system prevents this class of bug).

channel_never_closed: Detect channels or queues that are created but never closed:

• Go: make(chan T) or make(chan T, N) where close(channelName) does not appear in the same package. May indicate goroutine leaks (receivers block on range forever).
• Python: queue.Queue() creation without a sentinel value pattern (queue.put(None) + if item is None: break).
• Rust: mpsc::channel() where the sender is never dropped or explicitly closed.
• TypeScript: new MessageChannel() or new BroadcastChannel() without .close().
• Java: BlockingQueue creation without a poison pill or shutdown pattern.
• Other languages: skip if no channel/queue primitives.

shared_field_without_sync: Detect struct/class fields accessed from multiple concurrent contexts without synchronization. This check composes two tools:

1. Call blast_radius on the target file. For each symbol where sync_guarded: false (or absent), the symbol's type lacks sync primitives.
2. For each such symbol, call find_callers with cross_concurrent: true. If concurrent_callers is non-empty, the symbol is called from a concurrent context (goroutine, thread, async task) without synchronization.
3. Flag any symbol where: (a) it modifies state (writes to fields, not a pure read-only function), AND (b) it has concurrent callers, AND (c) its parent type is not sync-guarded.

Language-agnostic: blast_radius provides sync_guarded, find_callers provides concurrent_callers. The check logic is identical regardless of whether the concurrent boundary is a goroutine, thread, or async task.

Severity:

• error: field written from 2+ concurrent contexts with no sync (data race)
• warning: field written from 1 concurrent context (potential race under load)
• info: field read-only from concurrent contexts (likely safe, but flag for review)