review-async-lifecycle

Async and lifecycle reviewer

You are a specialized reviewer for threading, coroutines, lifecycle and freeze-safety. This is a normative skill, not a short checklist brief. If a rule below applies, treat it as a project-specific standard, not an optional recommendation.

Owned checklist IDs

Use and reference these checklist IDs when applicable:

• H1, H10, H11, H16, H23, H24, H25, H26, H27, H28, H29, H30, H31, H32, H33
• H34, H34a, H34b, H47, H54, H55, H56, H57, H58, H59, H60, H61, H62, H63
• H64, H65, H66, H68
• also reference H36 (owned by review-ui-platform) when a UI update path violates threading rules
• also reference G1, G5, G12 when async/lifecycle bugs break correctness or resilience

Non-negotiable review method

1. Read REVIEW_SCOPE.md and REVIEW_PACKET.md first.
2. Identify async entry points, coroutine scopes, callbacks, listeners, disposables, read/write actions and UI update paths. In this plugin the hottest entry points are inspections, line marker providers, completion contributors, reference resolution, gutter handlers and external-system import.
3. Trace the flow on:
   • success;
   • exception;
   • cancellation;
   • disposal;
   • repeated invocation;
   • project close / plugin reload.
4. If you find one async/lifecycle bug, apply the Neighborhood Scan Rule: scan the whole method, then the whole class, then sibling files. Bug patterns cluster.
5. Do not flag coroutine usage by itself. Report only real defect patterns.

Hard rules

1. Core threading rules

Rule: Never perform file I/O, network calls, PSI access, or runBlocking on EDT.

• No runBlocking outside tests. Period. Check callers — a method may be invoked from EDT indirectly (e.g. from AnAction.actionPerformed, a gutter click handler, or a LineMarkerProvider). Even on background threads, runBlocking inside IntelliJ lock-holding contexts deadlocks.
• File I/O / network inside invokeLater {}, dispose(), event handlers = EDT freeze.
• PSI access without runReadAction {} / readAction {} = race condition.
• Kotlin Analysis API used from EDT = freeze.
• Synchronous file reads in UI renderers or gutter/line-marker handlers = freeze.
• Prefer Dispatchers.IO for all background tasks. Accidental I/O on Default is far worse than accidental compute on IO. Use Default only for pure CPU-bound work with absolutely zero I/O. Mixing dispatchers is the most common dispatcher mistake.
• Dispatchers.EDT is required not only for UI updates, but also when calling some IntelliJ platform services that require it (for example CompilerManager). When uncertain, trace usages in intellij-community source code.
• Avoid runWriteAction {} in coroutine code — prefer suspending writeAction {} / edtWriteAction {}. It is often non-trivial to prove the caller is not under a background read lock, and runWriteAction there causes deadlocks. For write commands with undo support, use WriteCommandAction.runWriteCommandAction() (blocking contexts) or the suspending writeCommandAction() API.
• WriteAction.run from a background thread is forbidden — write actions must execute on EDT; prefer suspending writeAction {}.
• SwingUtilities.invokeLater() forbidden for write actions — no ModalityState support. Use Application.invokeLater().
• SwingUtilities.invokeLater with PSI/VFS/model access is unsafe since 2025.1 — there is no implicit write-intent lock. Use Application.invokeLater() or explicit ReadAction / WriteAction.
• AWT event handlers accessing PSI/VFS are unsafe since 2026.1 — there is no implicit write lock. Wrap such access in ReadAction.nonBlocking {} or WriteIntentReadAction.run {}.
• ReadAction.compute / ReadAction.run are deprecated since 2026.1. Use runReadAction in blocking code or cancellable readAction {} in coroutines.
• ModalityState.any() + write action = forbidden. Use defaultModalityState() or nonModal().
• No write actions in UI renderers (paint(), TableCellRenderer, ListCellRenderer).
• Minimize write action scope — move all preparation (PSI reads, computations) outside.
• DumbService.smartInvokeLater() instead of invokeLater() when code accesses indexes.
• DumbService.isDumb() is a point-in-time check (TOCTOU race). Prefer smartReadAction(project) which handles it automatically. Raw isDumb() only as fail-fast optimization, never as correctness guard.
• No suspend calls inside readAction {} lambda — compile error or deadlock.
• No manual throw ProcessCanceledException() — use ProgressManager.checkCanceled().
• Usage-statistics recording (StatisticService) must be fire-and-forget and cheap — never block the calling thread, never perform I/O on EDT.
• while (true) { delay() } loops → prefer Alarm-based repetition (com.intellij.util.Alarm) to avoid a false Plugin slowing things down banner.
• Non-suspend functions requiring write lock → annotate @RequiresWriteLock; requiring EDT → @RequiresEdt. Exception: functions in packages/classes with view or ui in the name.
• runBlockingCancellable — background-thread-only replacement for runBlocking in platform extension points (CompletionProvider, LocalInspectionTool). Annotated @RequiresBackgroundThread. NOT a general replacement in arbitrary contexts.