structured-coroutines

1.1.0indexed

Enforces structured concurrency for coroutines via compiler checks, static analyzers, IDE inspections, lint rules and annotations — compile-time errors, quick fixes, tool window, zero runtime overhead.

JSJVMNativeWasm·santimattius/structured-coroutines

123

Stars

—

Used by

dependents

Health

/ 100

Structured Coroutines

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.

Project Status

🎯 Purpose

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

Resource leaks from orphaned coroutines
Uncontrolled lifecycle with GlobalScope

This toolkit enforces structured concurrency best practices through:

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

📦 Toolkit Components

✨ Features

🚨 Rules Overview

51 documented patterns (v1.0.0) — single source of truth: docs/rule-codes.yml.
Full descriptions, examples, and suppression IDs: docs/BEST_PRACTICES_COROUTINES.md, docs/SUPPRESSING_RULES.md.

v1.0 highlights: COMPOSE_002/003, TEST_005/006, FLOW_009/011, INTEROP_003/004, DEBUG_001 (opt-in).
Platform guides: Compose · KMP · Ktor · Spring.

Per-module rule lists and configuration examples: detekt-rules · lint-rules · intellij-plugin.

📦 Installation

Compiler Plugin

// 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")
}

Detekt Rules

// 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")
}

Android Lint Rules

// 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.

IntelliJ/Android Studio Plugin

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:

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

Kotlin Multiplatform

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")
            }
        }
    }
}

🔧 Usage

Using @StructuredScope Annotation

Framework Scopes (Auto-recognized)

The plugin automatically recognizes lifecycle-aware framework scopes:

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


  : () {
     {
        lifecycleScope.launch { fetchData() }
    }
}



 {
     scope = rememberCoroutineScope()
    Button(onClick = { scope.launch { doWork() } }) {
        Text()
    }
}

Recognized Framework Scopes:

📋 Rule Details

1. No GlobalScope

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

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

2. No Inline CoroutineScope

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

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

3. No runBlocking in Suspend

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

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

4. No Job/SupervisorJob in Builders

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

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

5. No Extending CancellationException

// ❌ ERROR
class MyError : CancellationException()

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

6. Handle CancellationException

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

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

7. NonCancellable in Finally

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

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

8. No Blocking Calls (Detekt)

// ⚠️ 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()
    }
}

9. Use runTest in Tests (Detekt)

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

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

10. Cooperation Points in Loops (Detekt)

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


  {
     (item  items) {
        ensureActive()
        heavyWork(item)
    }
}

⚙️ Configuration

Detekt (detekt.yml)

📖 Full Documentation: Detekt Rules Documentation

🏗️ Architecture

🌍 Supported Platforms

🧪 Testing

# Publish locally
./gradlew publishToMavenLocal

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

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

# Run all tests
./gradlew test

🆚 Comparison

Notes:

Rule codes, severities, and layer matrix: docs/rule-codes.yml
Android Lint and IntelliJ include quick fixes; IDE adds intentions, gutter icons, and Flow Chain Analyzer

🛠️ Requirements

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)

📄 License

Copyright 2026 Santiago Mattiauda

Licensed under the Apache License, Version 2.0

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for setup, module layout, and how to add rules.

This project follows the Code of Conduct. Security issues should be reported per SECURITY.md, not via public issues.

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

📚 Documentation

Module Documentation

Each module contains its own detailed documentation:

Internationalization (i18n)

All user-facing text is externalized for localization:

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

Internationalization (i18n)

All user-facing text is externalized for localization:

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

External Resources

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

GRPC-Kotlin-Multiplatform★ 133

TimOrtelImplements client-side gRPC with support for parsing proto3 files, generating corresponding code, and suspending RPC calls. Features a DSL for creating proto objects and supports various proto types.Shared: kotlin-coroutines, gradle-plugin

kotlin-channel-event-bus★ 57

Kotlin-Multiplatform-FoundationImplements a thread-safe event bus using channels for multi-key, multi-producer, single-consumer communication. Supports unbounded and conflated channels, ensuring all events are consumed. Ideal for UI applications.Shared: kotlin-coroutines, coroutines

inspekt★ 43

rnettCompile-time reflection enabling inspection of classes, functions, properties and annotations, with top-level declaration support, suspend invocation, JVM-like proxies and dependency reflection.Shared: kotlin-coroutines, gradle-plugin

kotlin-parallel-operations★ 42

cvb941Facilitates parallel operations like map and reduce on collections using coroutines, enhancing performance with chunked operations for efficient multithreading and data locality benefits.Shared: kotlin-coroutines, coroutines

kotlin-jvm-blocking-bridge★ 94

Him188Generates blocking bridges for calling suspend functions from Java, simplifying integration. Automatically creates non-suspend bridge functions, ensuring minimal effort and high stability for production use.Shared: kotlin-coroutines, coroutines

mavlink-kotlin★ 78

divyanshupundirType-safe, high-performance MAVLink library addresses performance issues, provides modular code generation, and supports custom MAVLink message generation with user-defined adapters and connection handling.Shared: kotlin-coroutines, gradle-plugin

Compiler Plugin	✅ Complete (14 FIR checkers)	gradle-plugin/README.md
Gradle Plugin	✅ Complete (profiles incl. Spring/Ktor)	gradle-plugin/README.md
Detekt Rules	✅ Complete (40 rules)	detekt-rules/README.md
Android Lint	✅ Complete (35 detectors)	lint-rules/README.md
IntelliJ Plugin	✅ Complete (35 inspections, tool window, Flow Analyzer)	intellij-plugin/README.md
Annotations	✅ Complete	annotations/README.md
Sample	✅ Compilation examples per rule	compilation/README
Sample (Detekt)	✅ Detekt rule validation (30+ examples)	sample-detekt/README.md
Kotlin Coroutines Agent Skill	✅ AI/agent guidance	docs/KOTLIN_COROUTINES_SKILL.md

`compiler`	K2/FIR Compiler Plugin	Compile-time errors
`detekt-rules`	Detekt custom rules	Static analysis
`lint-rules`	Android Lint rules	Android projects
`intellij-plugin`	IntelliJ/Android Studio Plugin	Real-time IDE analysis
`annotations`	`@StructuredScope` annotation	Runtime/Compile
`gradle-plugin`	Gradle integration	Build configuration

Compiler (FIR)	14 checkers	7 errors + 7 warnings; INTEROP_001/002 in K2
Detekt	40 rules	KMP source-set aware; backend + Compose profiles
Android Lint	35 detectors	Android/Compose + shared compiler rules
IntelliJ	35 inspections	Real-time analysis, quick fixes, Flow Chain Analyzer

`viewModelScope`	Android ViewModel	`androidx.lifecycle`
`lifecycleScope`	Android Lifecycle	`androidx.lifecycle`
`rememberCoroutineScope()`	Jetpack Compose	`androidx.compose.runtime`

Gradle Plugin	gradle-plugin/README.md	Installation, configuration, severity settings
Detekt Rules	detekt-rules/README.md	40 rules with examples and configuration
Android Lint	lint-rules/README.md	35 detectors, Android/Compose-specific detection
IntelliJ Plugin	intellij-plugin/README.md	35 inspections, quick fixes, Flow Analyzer, K2 support
Annotations	annotations/README.md	@StructuredScope usage and multiplatform support
Compiler	compiler/README.md	K2/FIR checker implementation details
Sample (compilation)	compilation/README.md	One example per compiler rule (errors and warnings)
Sample (Detekt)	sample-detekt/README.md	One example per Detekt rule; run `:sample-detekt:detekt` to validate
Kotlin Coroutines Agent Skill	docs/KOTLIN_COROUTINES_SKILL.md	AI/agent skill and decision resource: 32 practices, strict rules, triage playbook (v2.0.0)
Best Practices	docs/BEST_PRACTICES_COROUTINES.md	Canonical guide to coroutine good/bad practices
Decision Guide	docs/DECISION_GUIDE.md	Quick-reference: launch vs async, scope, dispatcher, timeout, Flow
Suppressing Rules	docs/SUPPRESSING_RULES.md	Unified suppression IDs (Compiler, Detekt, Lint, IntelliJ) by rule code

JVM	✅	✅	❌	✅
Android	✅	✅	✅	✅
iOS	✅	✅	❌	✅
macOS	✅	✅	❌	✅
watchOS	✅	✅	❌	✅
tvOS	✅	✅	❌	✅
Linux	✅	✅	❌	✅
Windows	✅	✅	❌	✅
JS	✅	✅	❌	✅
WASM	✅	✅	❌	✅

Compiler Plugin	Compile	14 checkers	✅	❌	All (KMP)
Detekt Rules	Analysis	40 rules	✅	❌	All (KMP)
Android Lint Rules	Analysis	35 detectors	✅	❌	Android only
IDE Plugin	Editing	35 inspections	❌	✅	All
Combined (All)	All	51 patterns	✅	✅	-
Code Review	Manual	—	❌	❌	-
Runtime	Late	—	❌	❌	-