kotlin-no-globals Compiler Plugin

This module contains the K2 FIR compiler plugin implementation for kotlin-no-globals.

Use this module when you need direct compiler wiring or want to inspect the compiler-side enforcement model. For normal build setup, start with the Gradle plugin README, the rule guide, and the API reference.

Status

This module is pre-1.0 and publishes Kotlin-line-specific variants for the repository's supported Kotlin matrix.

It is responsible for:

  • detecting global var
  • detecting selected stored mutable val patterns
  • detecting singleton objects that are themselves mutable carriers
  • reporting diagnostics that require @RequiresGlobalState

Artifact Coordinate

The compiler plugin artifact is Kotlin-line-specific:

one.wabbit:kotlin-no-globals-plugin:<baseVersion>-kotlin-<kotlinVersion>

Example shape:

one.wabbit:kotlin-no-globals-plugin:0.1.1-kotlin-2.3.10

Use the variant whose Kotlin suffix matches the compiler you are running.

Installation And Direct Compiler Usage

If you are not using the Gradle plugin, pass the compiler plugin explicitly:

-Xplugin=/path/to/kotlin-no-globals-plugin.jar
-P plugin:one.wabbit.no-globals:enabled=true|false
-P plugin:one.wabbit.no-globals:blacklistedType=com.example.MutableBox

If your source code uses @RequiresGlobalState, the annotation library still needs to be present on the compilation classpath.

To verify the plugin is active, compile a source file containing a top-level var without @RequiresGlobalState. The compilation should fail with the plugin's global-state diagnostic.

Compiler Options

Supported options:

  • enabled
  • true or false
  • controls whether the plugin registers its FIR checkers
  • blacklistedType
  • repeatable
  • extends the built-in mutable-type blacklist

Malformed blacklist values fail fast during option parsing.

Implementation Shape

The compiler plugin currently uses:

  • a property checker for property-shaped global mutable state
  • a regular-class checker for singleton objects that are themselves mutable carriers

The enforcement model is simple:

  • find a declaration that matches the rule
  • require @RequiresGlobalState on that declaration
  • let Kotlin’s standard opt-in machinery enforce use-site acknowledgement

Scope

This compiler plugin is:

  • K2 only
  • FIR based
  • declaration-shape and declared-type driven by design

It does not currently attempt full hidden-mutability inference.

Release notes live in ../CHANGELOG.md. For diagnostics and setup issues, start with ../docs/troubleshooting.md and the contribution/support guidance in the root README.