kotlin-acyclic is a Kotlin compiler-plugin family for enforcing structural acyclicity rules in source code.

For a JVM project, the smallest useful setup is:

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

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
    }
}

rootProject.name = "acyclic-quickstart"

// build.gradle.kts
import one.wabbit.acyclic.gradle.AcyclicDeclarationOrderMode
import one.wabbit.acyclic.gradle.AcyclicEnforcementMode

plugins {
    kotlin("jvm") version "2.3.10"
    application
    id("one.wabbit.acyclic") version "0.1.0"
}

dependencies {
    implementation("one.wabbit:kotlin-acyclic:0.1.0")
}

kotlin {
    jvmToolchain(21)
}

application {
    mainClass = "sample.MainKt"
}

acyclic {
    compilationUnits.set(AcyclicEnforcementMode.OPT_IN)
    declarations.set(AcyclicEnforcementMode.ENABLED)
    declarationOrder.set(AcyclicDeclarationOrderMode.TOP_DOWN)
}

Then add src/main/kotlin/sample/Main.kt:

package sample

fun main() {
    println(render())
}

fun render(): String = helper()

fun helper(): String = "acyclic"

Run it:

./gradlew run

Expected output:

acyclic

This example is ordered for TOP_DOWN: earlier declarations depend only on later declarations. In most builds, the Gradle plugin resolves the Kotlin-matched compiler-plugin artifact automatically.

It is built for teams that want compile-time guardrails around declaration recursion, file-to-file dependency cycles, and source-order conventions without relying on lint-only heuristics or import-string analysis.

This repository is pre-1.0 and K2-only.

• Kotlin publish matrix is driven by supportedKotlinVersions in gradle.properties. The current matrix is 2.3.10 and 2.4.0-Beta1.
• The annotations library is Kotlin Multiplatform and uses JDK 21 for JVM compilation.
• The compiler plugin and Gradle plugin target JDK 21.
• The IntelliJ plugin targets JVM 17 and IntelliJ IDEA 2025.3.

This project is trying to be strict without becoming magical.

• dependency edges come from resolved semantics, not import-string heuristics
• declaration analysis stays scoped so users can predict what the rule means
• escape hatches are explicit and all-participants, not partial suppression tricks
• current limits are documented as product boundaries rather than treated as accidental quirks

Kotlin makes it easy to write elegant recursive code and to spread definitions across files. That is usually a strength. In larger codebases, it can also hide structural problems:

• mutually recursive declarations that make a file harder to reason about
• cross-file cycles that blur compilation-unit boundaries
• source-order conventions that drift because nothing enforces them

kotlin-acyclic makes those rules explicit and compile-time enforced.

The project enforces three related rule families.

Current boundary:

• declaration analysis is file-local today
• top-level declarations and declarations nested inside classes become declaration nodes
• local declarations are not separate nodes, but their resolved dependencies are attributed to the enclosing tracked declaration

These are current product boundaries, not hidden surprises:

• declaration analysis is same-file only
• cross-file declaration recursion is enforced by compilation-unit analysis, not by a module-wide declaration graph
• lexical containment is distinguished from semantic dependency for shapes like self return types, nested type containment, and enclosing-type references
• the rule set is structural and semantic, not arbitrary runtime recursion analysis

The Gradle plugin defaults are conservative:

• compilationUnits = OPT_IN
• declarations = DISABLED
• declarationOrder = NONE

In practice:

• file-level checks are available but not forced
• declaration-level checks stay off until explicitly enabled
• no source-order policy is imposed by default

The effective policy is resolved from broadest scope to narrowest scope:

1. Gradle defaults in acyclic {} or direct compiler-plugin options
2. file annotations such as @file:Acyclic and @file:AllowCompilationUnitCycles
3. declaration annotations such as @Acyclic, @AllowSelfRecursion, and @AllowMutualRecursion
4. declaration-level @Acyclic(order = DEFAULT|NONE|TOP_DOWN|BOTTOM_UP) for per-declaration order policy

Practical reading:

• build configuration establishes the default policy for the compilation
• file annotations can opt an entire file into checks, opt an entire file out of file-cycle checks, and set the default declaration-order policy for that file
• declaration annotations can opt individual tracked declarations in and carve out narrow, explicit exceptions
• @Acyclic(order = DEFAULT) resets one declaration back to the build-level order policy, not the file-level override

Lexical containment and nominal self-reference are not treated as declaration cycles:

package sample

sealed interface Token {
    class Word(val text: String) : Token
}

class Box {
    fun self(): Box = this
}

With declaration checking enabled, same-file mutual recursion is rejected:

package sample

fun a(): Int = b()

fun b(): Int = a()

With compilation-unit checking enabled, semantic cross-file cycles are rejected:

// sample/A.kt
package sample

class A(val b: B)

// sample/B.kt
package sample

class B(val a: A)

With declarationOrder = BOTTOM_UP, later declarations may depend on earlier ones, but not the reverse:

package sample

fun use(): Int = helper()

fun helper(): Int = 1

That file is valid under TOP_DOWN and rejected under BOTTOM_UP.

If an edge is already part of a reported declaration cycle, the cycle diagnostic wins and the redundant declaration-order diagnostic for that same edge is suppressed.

Opt-outs are narrow. A cycle is exempt only when every participant opts out:

package sample

import one.wabbit.acyclic.AllowMutualRecursion

@AllowMutualRecursion
fun even(n: Int): Boolean =
    if (n == 0) true else odd(n - 1)

@AllowMutualRecursion
fun odd(n: Int): Boolean =
    if (n == 0) false else even(n - 1)

The same all-participants rule applies at file scope with @file:AllowCompilationUnitCycles.

Most consumers only need the annotations library and the Gradle plugin.

The compiler plugin is published per Kotlin compiler line, using a version suffix of the form:

• one.wabbit:kotlin-acyclic-plugin:<baseVersion>-kotlin-<kotlinVersion>

For the current release train, the repository is configured to publish compiler-plugin variants for:

• 2.3.10
• 2.4.0-Beta1

The Gradle plugin chooses the matching compiler-plugin artifact automatically. If you integrate the compiler plugin directly, choose the artifact whose -kotlin-<kotlinVersion> suffix matches your compiler.

If you are not using Gradle, wire the compiler plugin directly:

-Xplugin=/path/to/kotlin-acyclic-plugin.jar
-P plugin:one.wabbit.acyclic:compilationUnits=disabled|opt-in|enabled
-P plugin:one.wabbit.acyclic:declarations=disabled|opt-in|enabled
-P plugin:one.wabbit.acyclic:declarationOrder=none|top-down|bottom-up

If source code uses one.wabbit.acyclic.*, the annotations library still needs to be present on the compilation classpath.

Before publication, or when testing locally across repositories, consumers should use both forms of composite-build wiring:

pluginManagement {
    includeBuild("../kotlin-acyclic")
}

includeBuild("../kotlin-acyclic")

The first resolves the Gradle plugin ID. The second lets Gradle substitute the annotations and compiler-plugin artifacts.

The IntelliJ plugin in this repository does not implement separate IDE-native inspections yet. Its current job is to help the bundled Kotlin IDE plugin load the external compiler plugin registrar for trusted projects that already apply kotlin-acyclic.

IntelliJ only exposes a coarse registry switch here, so enabling support for kotlin-acyclic enables all non-bundled K2 compiler plugins for the current trusted project session, not just this one.

Common commands from the repo root:

./gradlew build
./gradlew projects
./gradlew :kotlin-acyclic:compileKotlinMetadata
./gradlew :kotlin-acyclic-plugin:test
./gradlew :kotlin-acyclic-gradle-plugin:test
./gradlew :kotlin-acyclic-ij-plugin:test

To run the compiler plugin against a specific supported Kotlin line:

./gradlew -PkotlinVersion=2.3.10 :kotlin-acyclic-plugin:test
./gradlew -PkotlinVersion=2.4.0-Beta1 :kotlin-acyclic-plugin:test

• Published API docs: https://wabbit-corp.github.io/kotlin-acyclic/
• CHANGELOG.md: release notes and public-change history
• docs/ARCHITECTURE.md: repo-wide architecture, configuration flow, and analysis boundaries
• docs/api-reference.md: public API inventory and Dokka generation commands
• docs/migration.md: versioning policy, compatibility notes, and upgrade checklist
• docs/troubleshooting.md: common diagnostics, causes, and fixes
• docs/user-guide.md: installation, configuration, rule semantics, and source-level control model
• docs/development.md: local build, test, versioning, publishing, and composite-build notes
• library/README.md: source-level annotations and precedence details
• gradle-plugin/README.md: Gradle DSL, installation, and Kotlin version negotiation
• compiler-plugin/README.md: direct compiler integration and compiler-side behavior
• ij-plugin/README.md: IntelliJ plugin scope and lifecycle
• compiler-plugin/GOAL.md: design goals and semantics
• compiler-plugin/WALKTHROUGH.md: guided code-review path through the implementation

If you are new to the repository, this order usually works well:

1. README.md
2. docs/user-guide.md
3. docs/troubleshooting.md
4. docs/api-reference.md
5. docs/ARCHITECTURE.md
6. library/README.md
7. gradle-plugin/README.md
8. compiler-plugin/README.md
9. compiler-plugin/PLAN.md

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) for open source use.

Before contributions can be merged, contributors need to agree to the repository CLA.