A comprehensive toolkit for enforcing structured concurrency in Kotlin Coroutines, inspired by Swift Concurrency. It provides multiple layers of protection through compile-time checks and static analysis.

Kotlin Coroutines are powerful but can be misused, leading to:

• Resource leaks from orphaned coroutines
• Uncontrolled lifecycle with GlobalScope
• Difficult debugging due to scattered coroutine launches
• Deadlocks from runBlocking in suspend functions
• Broken cancellation from swallowed CancellationException
• Thread starvation from blocking calls in coroutines

This toolkit enforces structured concurrency best practices through:

1. Compiler Plugin - Errors at compile time (K2/FIR)
2. Detekt Rules - Static analysis warnings
3. Android Lint Rules - Android-specific static analysis with quick fixes

• 🔍 Compile-time detection of unsafe coroutine patterns
• 🚫 Error-level diagnostics for critical violations
• ⚠️ Warning-level diagnostics for code smells
• 🎯 Opt-in model via @StructuredScope annotation
• 🤖 Framework-aware - recognizes viewModelScope, lifecycleScope, rememberCoroutineScope()
• 🔧 K2/FIR compatible - works with Kotlin 2.3+
• 📦 Zero runtime overhead - all checks happen at compile time
• 🌍 Kotlin Multiplatform - supports JVM, JS, Native, WASM
• 🔎 Detekt integration - additional static analysis rules
• 📱 Android Lint integration - Android-specific rules with quick fixes
• 📋 Structured Coroutines tool window (IntelliJ) - view all findings for the current file in one place
• 📂 Compilation samples - one example per compiler rule in the sample project
• 📂 Detekt validation samples - sample-detekt module with one example per Detekt rule ( ./gradlew :sample-detekt:detekt)
• 🤖 Kotlin Coroutines Agent Skill - consistent AI/agent-driven guidance for coroutine code

Total: 18 Detekt Rules (10 from Compiler Plugin + 8 Detekt-only)

Total: 21 Android Lint Rules (9 from Compiler Plugin + 4 Android-specific + 8 additional)

The IDE plugin provides real-time inspections, quick fixes, intentions, and gutter icons.

• Scope Type Icons: Visual indicators for viewModelScope (green), lifecycleScope (blue), GlobalScope (red), etc.
• Dispatcher Context Icons: Shows current dispatcher (Main, IO, Default, Unconfined)

• View → Tool Windows → Structured Coroutines: Lists all inspection findings for the current file (severity, location, inspection name, message). Use Refresh to run inspections; * double-click* a row to navigate to the issue. The plugin correctly recognizes @StructuredScope on parameters and properties, so annotated scopes are not reported as unstructured.

// settings.gradle.kts
pluginManagement {
    repositories {
        mavenLocal()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.3.0"
    id("io.github.santimattius.structured-coroutines") version "0.1.0"
}

dependencies {
    implementation("io.github.santimattius:structured-coroutines-annotations:0.1.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
}

// build.gradle.kts
plugins {
    id("io.gitlab.arturbosch.detekt") version "1.23.7"
}

dependencies {
    detektPlugins("io.github.santimattius:structured-coroutines-detekt-rules:0.1.0")
}

// build.gradle.kts (Android project)
dependencies {
    lintChecks("io.github.santimattius:structured-coroutines-lint-rules:0.1.0")
}

Note: Android Lint Rules are only available for Android projects. For multiplatform projects, use the Compiler Plugin or Detekt Rules.

Install from JetBrains Marketplace or build from source:

# Build the plugin
./gradlew :intellij-plugin:build

# Run IDE sandbox for testing
./gradlew :intellij-plugin:runIde

Or install manually:

1. Go to Settings > Plugins > Install Plugin from Disk
2. Select intellij-plugin/build/distributions/intellij-plugin-*.zip

plugins {
    kotlin("multiplatform") version "2.3.0"
    id("io.github.santimattius.structured-coroutines") version "0.1.0"
}

kotlin {
    jvm()
    iosArm64()
    iosSimulatorArm64()
    js(IR) { browser(); nodejs() }

    sourceSets {
        commonMain {
            dependencies {
                implementation("io.github.santimattius:structured-coroutines-annotations:0.1.0")
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
            }
        }
    }
}

import io.github.santimattius.structured.annotations.StructuredScope

// Function parameter
fun loadData(@StructuredScope scope: CoroutineScope) {
    scope.launch { fetchData() }
}

// Constructor injection
class UserService(
    @property:StructuredScope
    private val scope: CoroutineScope
) {
    fun fetchUser(id: String) {
        scope.launch { /* ... */ }
    }
}

// Class property
class Repository {
    @StructuredScope
    private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())

    fun fetchData() {
        scope.launch { /* ... */ }
    }
}

The plugin automatically recognizes lifecycle-aware framework scopes:

// ✅ Android ViewModel - No annotation needed
class MyViewModel : ViewModel() {
    fun load() {
        viewModelScope.launch { fetchData() }
    }
}

// ✅ Android Activity/Fragment - No annotation needed
class MyActivity : AppCompatActivity() {
    fun load() {
        lifecycleScope.launch { fetchData() }
    }
}

// ✅ Jetpack Compose - No annotation needed
@Composable
fun MyScreen() {
    val scope = rememberCoroutineScope()
    Button(onClick = { scope.launch { doWork() } }) {
        Text("Click")
    }
}

Recognized Framework Scopes:

// ❌ ERROR
GlobalScope.launch { work() }

// ✅ Use framework scopes or @StructuredScope
viewModelScope.launch { work() }

// ❌ ERROR
CoroutineScope(Dispatchers.IO).launch { work() }

// ✅ Use a managed scope
class MyClass(@StructuredScope private val scope: CoroutineScope) {
    fun doWork() = scope.launch { work() }
}

// ❌ ERROR
suspend fun bad() {
    runBlocking { delay(1000) }
}

// ✅ Just suspend
suspend fun good() {
    delay(1000)
}

// ❌ ERROR
scope.launch(Job()) { work() }
scope.launch(SupervisorJob()) { work() }

// ✅ Use supervisorScope
suspend fun process() = supervisorScope {
    launch { task1() }
    launch { task2() }
}

// ❌ ERROR
class MyError : CancellationException()

// ✅ Use regular Exception
class MyError : Exception()

// ⚠️ WARNING - May swallow cancellation
suspend fun bad() {
    try {
        work()
    } catch (e: Exception) {
        log(e)
    }
}

// ✅ Handle separately
suspend fun good() {
    try {
        work()
    } catch (e: CancellationException) {
        throw e
    } catch (e: Exception) {
        log(e)
    }
}

// ⚠️ WARNING - May not execute
try {
    work()
} finally {
    saveToDb()  // Suspend call
}

// ✅ Protected
try {
    work()
} finally {
    withContext(NonCancellable) {
        saveToDb()
    }
}

// ⚠️ Detekt WARNING
scope.launch {
    Thread.sleep(1000)      // Blocking!
    inputStream.read()       // Blocking I/O!
    jdbcStatement.execute()  // Blocking JDBC!
}

// ✅ Use non-blocking alternatives
scope.launch {
    delay(1000)
    withContext(Dispatchers.IO) {
        inputStream.read()
    }
}

// ⚠️ Detekt WARNING - Slow test
@Test
fun test() = runBlocking {
    delay(1000)  // Real delay!
}

// ✅ Fast test with virtual time
@Test
fun test() = runTest {
    delay(1000)  // Instant!
}

// ⚠️ Detekt WARNING - Can't cancel
suspend fun process(items: List<Item>) {
    for (item in items) {
        heavyWork(item)  // No cooperation point
    }
}

// ✅ Can be cancelled
suspend fun process(items: List<Item>) {
    for (item in items) {
        ensureActive()
        heavyWork(item)
    }
}

structured-coroutines:
  # Compiler Plugin Rules 
  GlobalScopeUsage:
    active: true
    severity: error
  InlineCoroutineScope:
    active: true
    severity: error
  RunBlockingInSuspend:
    active: true
    severity: warning
  DispatchersUnconfined:
    active: true
    severity: warning
  CancellationExceptionSubclass:
    active: true
    severity: error

  # Detekt-Only Rules
  BlockingCallInCoroutine:
    active: true
    excludes: [ 'commonMain', 'iosMain' ]  # JVM-only
  RunBlockingWithDelayInTest:
    active: true
  ExternalScopeLaunch:
    active: true
  LoopWithoutYield:
    active: true

📖 Full Documentation: Detekt Rules Documentation

structured-coroutines/
├── annotations/          # @StructuredScope (Multiplatform)
├── compiler/             # K2/FIR Compiler Plugin
│   ├── UnstructuredLaunchChecker
│   ├── RunBlockingInSuspendChecker
│   ├── JobInBuilderContextChecker
│   ├── DispatchersUnconfinedChecker
│   ├── CancellationExceptionSubclassChecker
│   ├── SuspendInFinallyChecker
│   ├── CancellationExceptionSwallowedChecker
│   ├── UnusedDeferredChecker
│   ├── RedundantLaunchInCoroutineScopeChecker
│   └── LoopWithoutYieldChecker
├── detekt-rules/         # Detekt Custom Rules
│   ├── GlobalScopeUsageRule
│   ├── InlineCoroutineScopeRule
│   ├── RunBlockingInSuspendRule
│   ├── DispatchersUnconfinedRule
│   ├── CancellationExceptionSubclassRule
│   ├── BlockingCallInCoroutineRule
│   ├── RunBlockingWithDelayInTestRule
│   ├── ExternalScopeLaunchRule
│   ├── LoopWithoutYieldRule
│   ├── ScopeReuseAfterCancelRule
│   ├── ChannelNotClosedRule
│   ├── ConsumeEachMultipleConsumersRule
│   └── FlowBlockingCallRule
├── lint-rules/           # Android Lint Rules
│   ├── GlobalScopeUsageDetector
│   ├── MainDispatcherMisuseDetector
│   ├── ViewModelScopeLeakDetector
│   └── ... (21 rules total)
├── intellij-plugin/      # IntelliJ/Android Studio Plugin
│   ├── inspections/      # 13 real-time inspections (incl. LoopWithoutYield, LifecycleAwareFlowCollection)
│   ├── quickfixes/       # 12 automatic quick fixes
│   ├── intentions/       # 6 refactoring intentions (incl. Convert to runTest)
│   ├── guttericons/      # Scope & dispatcher visualization
│   └── view/             # Tool window (findings list, runner, tree visitor)
├── gradle-plugin/        # Gradle Integration
├── sample/               # Examples
│   └── compilation/     # One example per compiler rule (errors & warnings)
└── kotlin-coroutines-skill/  # AI/agent skill for coroutine best practices

# Publish locally
./gradlew publishToMavenLocal

# Run compiler plugin tests
./gradlew :compiler:test

# Run detekt rules tests
./gradlew :detekt-rules:test

# Run all tests
./gradlew test

Notes:

• Detekt Rules: 10 from Compiler Plugin + 8 Detekt-only = 18 rules total
• Android Lint Rules: 9 from Compiler Plugin + 4 Android-specific + 8 additional = 21 rules total
• Android Lint Rules include quick fixes for better developer experience
• IDE Plugin: 13 inspections + 12 quick fixes + 6 intentions + gutter icons for real-time feedback

• Kotlin 2.3.0+
• K2 compiler (default in Kotlin 2.3+)
• Gradle 8.0+
• Detekt 1.23+ (for detekt-rules)
• IntelliJ IDEA 2024.3+ / Android Studio Ladybug+ (for intellij-plugin)

Copyright 2026 Santiago Mattiauda

Licensed under the Apache License, Version 2.0

Contributions welcome! Please submit a Pull Request.

git clone https://github.com/santimattius/structured-coroutines.git
cd structured-coroutines
./gradlew publishToMavenLocal
./gradlew test

Each module contains its own detailed documentation:

All user-facing text is externalized for localization:

• Compiler plugin: Messages are in compiler/src/main/resources/messages/CompilerBundle*.properties. Default language is English so builds and CI are predictable. To use Spanish (or the JVM default locale), set the system property:
  • Spanish: -Dstructured.coroutines.compiler.locale=es (e.g. in gradle.properties: org.gradle.jvmargs=... -Dstructured.coroutines.compiler.locale=es)
  • JVM default: -Dstructured.coroutines.compiler.locale=default
• IntelliJ plugin: Uses StructuredCoroutinesBundle.properties; the IDE uses the platform language. Spanish: StructuredCoroutinesBundle_es.properties.

To add a new language, add a _<locale> properties file (e.g. CompilerBundle_de.properties) with the same keys.

All user-facing text is externalized for localization:

• Compiler plugin: Messages are in compiler/src/main/resources/messages/CompilerBundle*.properties. Default language is English so builds and CI are predictable. To use Spanish (or the JVM default locale), set the system property:
  • Spanish: -Dstructured.coroutines.compiler.locale=es (e.g. in gradle.properties: org.gradle.jvmargs=... -Dstructured.coroutines.compiler.locale=es)
  • JVM default: -Dstructured.coroutines.compiler.locale=default
• IntelliJ plugin: Uses StructuredCoroutinesBundle.properties; the IDE uses the platform language. Spanish: StructuredCoroutinesBundle_es.properties.

To add a new language, add a _<locale> properties file (e.g. CompilerBundle_de.properties) with the same keys.

• Kotlin Coroutines Guide
• Structured Concurrency
• Detekt Documentation
• Android Lint API
• IntelliJ Plugin SDK
• K2 Compiler Guide