lsp-inspect

---
name: lsp-inspect
description: Full code quality audit for a file, package, or directory. Supports batch mode (directory walk with --top ranking), comparison mode (--diff for branch-only issues), severity calibration by blast radius, fix suggestions, and confidence tiers. Applies a check taxonomy (dead symbols, silent failures, error wrapping, coverage gaps, test coverage, doc drift, unrecovered panics, context propagation, concurrency safety) using LSP-first strategies. Concurrency checks cover 25 languages across 4 families (goroutine, thread, async, actor). Produces a severity-tiered findings report. Language-agnostic.
argument-hint: "<file-or-directory> [--checks <type1>,<type2>] [--json] [--top N] [--diff]"
user-invocable: true
allowed-tools: mcp__lsp__start_lsp mcp__lsp__open_document mcp__lsp__blast_radius mcp__lsp__find_references mcp__lsp__list_symbols mcp__lsp__inspect_symbol mcp__lsp__get_diagnostics mcp__lsp__find_callers mcp__lsp__go_to_definition mcp__lsp__get_server_capabilities mcp__lsp__get_cross_repo_references Bash
license: MIT
compatibility: Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)
metadata:
  required-capabilities: documentSymbolProvider referencesProvider
  optional-capabilities: callHierarchyProvider
---

> 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

**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)

### Step 3: Cross-check and classify

For each finding, assign:

**Severity (calibrated by blast radius):**
- `error`: Will cause runtime failure, data loss, or resource leak, OR any finding where `non_test_callers >= 10` (high blast radius amplifies severity)
- `warning`: May cause confusion, maintenance burden, or subtle bugs, OR findings where `non_test_callers` is 3-9
- `info`: Style issue or improvement opportunity, OR `non_test_callers <= 2`

Use the `non_test_callers` count from Step 1's `blast_radius` result as a
severity multiplier. A silent failure in a function with 50 callers is
error-severity; the same pattern with 2 callers is info.

**Cross-file impact scoring:** For every finding, look up the symbol's
`non_test_callers` count from Step 1's blast_radius result. Use this as a
severity multiplier: if non_test_callers >= 10, escalate severity by one tier
(info->warning, warning->error). Document the caller count in the finding.

**Confidence tiers:**
- `verified`: LSP-confirmed (Tier 1A/1B) or unambiguous code pattern (act immediately)
- `suspected`: Heuristic match with possible false positive (pattern match, investigate first)
- `advisory`: Grep-based or uncertain pattern match (style, optional)

### Step 4: Output

Produce the findings report:

```markdown
## Inspection Report: <target>

**Files analyzed:** N
**Checks applied:** [list]
**Findings:** E errors, W warnings, I info

### Errors

| # | Check | File:Line | Finding | Confidence | Fix |
|---|-------|-----------|---------|------------|-----|
| 1 | dead_symbol | pkg/foo.go:42 | `UnusedHelper` has 0 references (0 callers) | verified (LSP) | Remove lines 42-55 (function `UnusedHelper`) |

### Warnings

| # | Check | File:Line | Finding | Confidence | Fix |
|---|-------|-----------|---------|------------|-----|
| 1 | error_wrapping | pkg/bar.go:88 | `return err` without context wrapping (5 callers) | verified | Change `return err` to `return fmt.Errorf("funcName: %w", err)` |
| 2 | test_coverage | pkg/foo.go:15 | `ProcessInput` has 0 test callers (8 callers) | verified (LSP) | Add test for `ProcessInput` in foo_test.go |

### Info

| # | Check | File:Line | Finding | Confidence | Fix |
|---|-------|-----------|---------|------------|-----|
| 1 | doc_drift | pkg/foo.go:20 | Docstring mentions `timeout` param, signature has `deadline` (1 caller) | suspected | Update docstring parameter name from timeout to deadline |
```

**Fix suggestions per check type:**
- `dead_symbol`: "Remove lines N-M (function `FuncName`)"
- `error_wrapping`: "Change `return err` to `return fmt.Errorf(\"funcName: %w\", err)`"
- `silent_failure`: "Add `return fmt.Errorf(...)` after the if block"
- `test_coverage`: "Add test for `FuncName` in file_test.go"
- `coverage_gap`: "Add default case to switch statement at line N"
- `doc_drift`: "Update docstring parameter name from X to Y"
- `panic_not_recovered`: "Add `defer func() { if r := recover()... }()` at goroutine start"
- `context_propagation`: "Replace `context.Background()` with `ctx` parameter"

When `--json` is passed, emit structured JSON with the same fields.

### Step 4.5: Batch ranking

When multiple files are analyzed, sort all findings by: (1) severity tier
(error > warning > info), (2) blast radius (non_test_callers descending),
(3) file path alphabetically. Emit only the top N findings (default 20,
controlled by --top flag). Append a summary line: 'Showing N of M total findings.'

### Step 5: Persist results

After producing the findings report, write a JSON file to
`.agent-lsp/last-inspection.json` in the workspace root. The JSON schema:

```json
{
  "target": "<original target path>",
  "timestamp": "<ISO 8601>",
  "files_analyzed": N,
  "findings": [
    {
      "severity": "error|warning|info",
      "confidence": "verified|suspected|advisory",
      "check": "<check_type>",
      "file": "<path>",
      "line": N,
      "finding": "<description>",
      "fix": "<exact fix text>",
      "blast_radius": N
    }
  ],
  "summary": {"errors": N, "warnings": N, "info": N}
}
```

This file is served by the `inspect://last` MCP resource for programmatic access.

## Caveats

1. **Re-exports:** Symbols in `__init__.py` (Python), `index.ts` (TypeScript),
   or public API surface files may appear dead locally but are consumed externally.
   Check `__all__`, barrel exports, and package-level re-exports before classifying.

2. **Registration patterns:** Symbols passed as values to framework registrars
   (HTTP handlers, plugin hooks) show zero LSP references. Grep wiring files
   before confirming dead.

3. **Library public API:** If the target is a library consumed by external repos,
   zero internal references doesn't mean dead. Use `--consumer-repos` or note
   as "library export, verify externally."

4. **Heuristic checks are advisory.** Silent failure and error wrapping checks
   depend on LLM reasoning about intent. False positives are expected; always
   review before acting on findings.

5. **Large files:** For files over 500 lines, read targeted sections (use
   offset/limit). Do not read entire large files into context.