lsp-concurrency-audit

Files (1)

• SKILL.md

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-concurrency-audit

Given a type or file, map all fields, identify which are accessed from multiple
concurrent contexts, and flag fields that lack synchronization. Produces a
field-level concurrency safety report.

## When to Use

- Before refactoring a type that is accessed from goroutines/threads
- Auditing a codebase for data race candidates
- Reviewing a PR that adds concurrent access to an existing type
- Understanding which fields in a type need mutex protection

## Input

```
/lsp-concurrency-audit <file-path> [--type <TypeName>]
```

If `--type` is provided, audit only that type. Otherwise, audit all types in
the file that have concurrent callers.

## Step 1: Discover types and fields

Call `list_symbols` on the target file to enumerate all types (structs, classes):

```
mcp__lsp__list_symbols({ "file_path": "<target>" })
```

For each type (kind=23 struct, kind=5 class), collect:
- Type name
- All fields (children with kind=8 field or kind=7 variable)
- Whether any field's name or detail contains sync primitives
  ("Mutex", "RWMutex", "Lock", "Semaphore", "atomic", "Atomic", "sync.",
  "pthread_mutex", "std::mutex")

If `--type` was specified, filter to that type only.

## Step 2: Blast radius and sync-guarded status

Call `blast_radius` on the file:

```
mcp__lsp__blast_radius({
  "changed_files": ["<target>"],
  "scope": "all"
})
```

From the result, for each method on each target type:
- Record `sync_guarded: true/false` from the response
- Record `non_test_callers` count (blast radius)
- Record `test_callers` count

## Step 3: Trace concurrent boundaries

For each method on each target type, call `find_callers` with
`cross_concurrent: true`:

```
mcp__lsp__find_callers({
  "file_path": "<target>",
  "line": <method_line>,
  "column": <method_column>,
  "direction": "incoming",
  "cross_concurrent": true
})
```

Record for each method:
- `concurrent_callers`: list of callers that cross concurrent boundaries
- `pattern`: the concurrent entry pattern detected (e.g., "go func(", "Thread.start(")

## Step 4: Classify fields

For each field in each type, determine its safety status:

**SAFE:** The type is sync-guarded (has a mutex/lock field) AND all methods
that access this field acquire the lock before access. Confidence: verified
if the type has a sync primitive; suspected if relying on external locking.

**UNSAFE (data race candidate):** The field is accessed by methods that have
`concurrent_callers` AND the type has no sync primitive. This is a potential
data race.

**WRITE-CONCURRENT:** The field is written by a method that has concurrent
callers. Higher severity than read-only concurrent access.

**READ-ONLY:** The field is only read (not written) from concurrent contexts.
Lower severity; often safe but worth flagging for review.

Severity assignment:
- `error`: UNSAFE + WRITE-CONCURRENT (probable data race)
- `warning`: UNSAFE + READ-ONLY (potential race under high concurrency)
- `info`: SAFE (sync-guarded, for documentation)

## Step 5: Output

```markdown
## Concurrency Audit: <TypeName>

**File:** <file_path>
**Fields:** N total, M sync-guarded
**Concurrent methods:** K (methods called from goroutines/threads/tasks)

### Field Safety Report

| Field | Type | Sync | Concurrent Writers | Concurrent Readers | Status |
|-------|------|------|-------------------|-------------------|--------|
| mu | sync.RWMutex | (is sync) | - | - | SYNC PRIMITIVE |
| sender | NotificationSender | guarded | 2 (SetSender, Send) | 3 | SAFE |
| subscribers | []Subscriber | none | 1 (Subscribe) | 2 | UNSAFE (write-concurrent) |

### Concurrent Call Sites

For each UNSAFE field, list the concurrent callers:

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp