Skip to content

Support Kotlin 2.4.20 - #100

Closed
jamesarich wants to merge 1 commit into
InsertKoinIO:1.1.1from
jamesarich:feat/kotlin-2.4.20-adapter
Closed

jamesarich wants to merge 1 commit into
InsertKoinIO:1.1.1from
jamesarich:feat/kotlin-2.4.20-adapter

Conversation

@jamesarich

Copy link
Copy Markdown

Kotlin 2.4.20 (2026-09-07) removes or re-signs four compiler APIs the plugin core binds, so 1.1.0 fails on every target with IrGenerationExtensionException / NoSuchMethodError. Fixes #89.

The core compiles against the floor (compileOnly(kotlin("compiler")), catalog kotlin = "2.3.20"), so all four are binary breaks: the source still compiles, and nothing shows up until a user runs 2.4.20. That is exactly what KotlinVersionAdapter is for, so this PR uses it rather than working around it.

What breaks

Measured with tools/abi-check/check-kotlin-abi.sh over the core's 416 org.jetbrains.kotlin references. Baseline before this PR: 0 missing on 2.3.20 / 2.4.0 / 2.4.10, 4 missing on 2.4.20 — so 2.4.20 is the whole delta.

API change in 2.4.20 call sites
IrUtilsKt.getValueArgument(IrConstructorCall, Name) removed 9
IrAnnotationImpl.setArgumentMapping(Map) removed; argumentMapping is now a read-only IrAnnotationArgsView computed from arguments + symbol 1
IrFactory.createSimpleFunction(...) gained a trailing IrClassSymbol parameter 12
FirResolvedQualifier.classId removed; symbol renamed to qualifierSymbol 1

Why the 1.1.1 warning change does not cover this

RELEASE_NOTES_1.1.1.md relaxes the "newer than tested" warning from patch to minor-line granularity, verified against 2.4.10, and its own process note says to run abi-check on each new patch before relying on that. 2.4.20 is the case where the assumption does not hold. Worse, without a registered adapter the relaxed warning would have suppressed the one diagnostic that points at the cause, which is what users on #89 are hitting.

What changed

  • New kotlin-2.4.20 adapter module, registered in kotlin-version-adapters.properties and supported-kotlin-versions.txt, embedded in the published jar like the existing two. Its source is identical to the 2.4.0 adapter; only the bytecode differs, which is the point.
  • Three new KotlinVersionAdapter members for the version-split operations: createSimpleFunction, setAnnotationArgumentMapping, classIdOf. Each carries a @KotlinApiChange documenting the incompatibility, per the "keep this interface minimal" rule.
  • createSimpleFunction exposes only the parameters that actually vary across the 12 call sites. Every site passes the same final / non-inline / non-expect / non-tailrec / non-operator / non-infix / non-external / no-container-source / not-fake-override shape, so those are fixed inside each adapter. Generated code is unchanged, which the golden files confirm.
  • getValueArgument(Name) is replaced core-side by a name-based getRegularArgument(Name) in IrArgumentMapping.kt, next to the existing index-based one. No adapter member needed: it is built on regularParameters, which is stable across every supported line. This is the overload that file's own comment missed, because it survived 2.4.0 and 2.4.10.
  • setAnnotationArgumentMapping is a no-op on 2.4.20 and documented as such: the mapping is derived from the positional arguments the caller already set. On 2.3.20 and 2.4.0 it sets the field, and errors rather than silently dropping the mapping if handed something that is not an IrAnnotationImpl.

Verification

Guard 1, don't break the current API. No golden file changed. git status koin-compiler-plugin/testData is clean, including every *_missing_d001.errors.txt. The transformations emit identical IR.

abi-check, all four supported versions. 0 missing for the core on 2.3.20, 2.4.0, 2.4.10 and 2.4.20. Each adapter module also resolves cleanly against its own target. For contrast, the 2.4.0 adapter carrying the new members resolves with 3 missing against 2.4.20, which is why the new module is required rather than optional.

Guard 2, tests. Full suite green: 372 tests, 38 classes, 0 failures. Compile-safety and diagnostics specifically: JvmDiagnosticTestGenerated 47, JvmErrorMessageTestGenerated$Diagnostics 47, JvmBoxTestGenerated$Safety 38, KoinDiagnosticTest 21, CompileSafetyValidatorSentinelTest 1, all 0 failures.

Guard 2, KLIB targets. test-apps on Kotlin 2.4.20 against this build: compileKotlinJvm, compileKotlinJs and compileKotlinWasmJs all green, and jvmTest passes 33 tests.

Real-world KMP graph. Also validated against Meshtastic-Android, a ~17k-file KMP app with 393 Koin annotation sites across 263 files and 17 modules: kmpSmokeCompile green across JVM and iosSimulatorArm64 (Kotlin/Native, so real KLIB codegen), then allTests green at 7598 tests, 0 failures. No adapter-fallback warning, so 2.4.20 selects its own adapter exactly.

There is no box test for this, and I do not think one is possible: the failure only reproduces under a specific compiler version, and the box harness runs one. check-kotlin-abi.sh is the real regression test for this class of bug, which leads to the next point.

Three things noticed while doing this

  1. check-kotlin-abi.sh is not in CI. supported-kotlin-versions.txt says it "drives the CI matrix", but build.yml and release.yml reference no Kotlin version at all — build.yml is a single ./gradlew build. So nothing would have caught this before a release, and nothing will catch the next one. Happy to wire the script into a matrix job as a follow-up PR if you want it.
  2. abi-check only scans koin-compiler-plugin/build/classes/kotlin/main, never the adapter modules, so a break in an adapter is invisible to it. Also worth a follow-up.
  3. ./gradlew :sample-app:jvmRun from CLAUDE.md's Build Commands does not work: mainClass points at examples.annotations.AnnotationsConfigTestKt and there is no fun main anywhere in sample-app. Pre-existing and untouched here, flagging it per the surprise rule.

Kotlin 2.4.20 removes or re-signs four compiler APIs the plugin core binds:
getValueArgument(IrConstructorCall, Name), IrAnnotationImpl.setArgumentMapping,
IrFactory.createSimpleFunction and FirResolvedQualifier.classId. The plugin core
is compiled against the 2.3.20 floor, so these surface at runtime as
IrGenerationExtensionException / NoSuchMethodError rather than at build time.

Adds a kotlin-2.4.20 adapter module and moves the three version-split operations
behind KotlinVersionAdapter. getValueArgument is replaced core-side by a
name-based getRegularArgument built on regularParameters, which is stable across
every supported line.

abi-check reports 0 missing for the core on 2.3.20, 2.4.0, 2.4.10 and 2.4.20.
Test suite green, no golden-file changes.

Fixes InsertKoinIO#89
@jamesarich jamesarich mentioned this pull request Sep 8, 2026
@the-best-is-best

Copy link
Copy Markdown

Anyone tell me when be ready?

@arnaudgiuliani
arnaudgiuliani deleted the branch InsertKoinIO:1.1.1 September 9, 2026 12:39
@jamesarich jamesarich mentioned this pull request Sep 9, 2026
@jamesarich

Copy link
Copy Markdown
Author

Reopened as #102 against main. This one auto-closed when the 1.1.1 base branch was deleted, and GitHub won't let a closed PR change base or reopen without it.

Rebased, and picked up one more call site: createIncludesHintFunction landed in 1.2.0 with a raw irFactory.createSimpleFunction.

@arnaudgiuliani

Copy link
Copy Markdown
Member

I'm fixing it in another branch 👍
Sorry for the branch closing

@jamesarich

Copy link
Copy Markdown
Author

I'm fixing it in another branch 👍 Sorry for the branch closing

No worries, as long as it's getting handled 😅 - appreciate y'all 💚

@arnaudgiuliani

Copy link
Copy Markdown
Member

Yes released in 1.2.1 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants