analysis-api-bump

name	analysis-api-bump
description	Bump the Kotlin version together with the version-locked Analysis API `-for-ide` artifacts and their runtime-dep pins, then verify source analysis still works. Use when upgrading Kotlin, when the Analysis API fails to resolve types after a bump, or when auditing whether the coupled pins are still correct.
disable-model-invocation	true
argument-hint	[target Kotlin version, e.g. 2.4.10]

Bump Kotlin + Analysis API (version-locked)

The Analysis API (standalone K2/FIR) is the single most version-fragile part of this repo. Kotlin and every *-for-ide artifact must share the exact same version, and two runtime deps (caffeine, coroutines-intellij) are pinned to match what the bundled IntelliJ core expects. Getting this wrong shows up as NoSuchMethodError / NoClassDefFoundError at runtime or as silent loss of type resolution — never a clean compile error. Follow the steps; do not eyeball it.

1. Snapshot the current pins

Read gradle/libs.versions.toml and record:

• kotlin — the shared version ref used by all of: kotlin-metadata-jvm, analysis-api-standalone, analysis-api-high-level, analysis-api-k2, analysis-api-low-level-fir, analysis-api-impl-base, analysis-api-platform, analysis-api-symbol-light-classes, kotlin-compiler, plus the kotlin-* plugins.
• caffeine (comment: "runtime dep of the Analysis API -for-ide jars; matches Kotlin's own pin").
• coroutines-intellij (comment: "JetBrains coroutines fork the bundled IJ core expects (KT-81457)").
• compose (comment: "aligned to Kotlin X.Y.Z") — Compose is Kotlin-coupled too.

Because every Analysis-API artifact uses version.ref = "kotlin", bumping the single kotlin entry moves them all. The risk is not forgetting one artifact — it's the three coupled satellites (caffeine, coroutines-intellij, compose) and undocumented API breaks.

2. Confirm the target and its coupled expectations (official sources)

For $ARGUMENTS (or the intended target Kotlin version), verify against official sources:

• kotlinlang.org release notes / Kotlin GitHub release: is this a stable release? Any Analysis API / standalone breaking changes called out?
• The -for-ide artifacts exist for this version in the IntelliJ dependencies repo (https://www.jetbrains.com/intellij-repository/), not just on Maven Central.
• Does the new Kotlin change the caffeine version its -for-ide jars expect? (Check the Kotlin build's own bundled version.) If so, update the caffeine pin to match and update the comment.
• Is KT-81457 fixed in this version, making the coroutines-intellij fork pin unnecessary? If yes, that's a chance to drop the fork; if not, keep the pin.
• Compose Multiplatform ↔ Kotlin compatibility: pick the compose version aligned to the new Kotlin (JetBrains compatibility table) and update the # aligned to Kotlin … comment.

Delegate this research to the kotlin-currency and deps-currency subagents if a broad check is wanted — they research official sources and respect the documented pins.

3. Apply the bump

In gradle/libs.versions.toml only (never inline versions):

• Set kotlin = "<target>".
• Update caffeine, coroutines-intellij, compose only if step 2 showed the constraint moved — and update their explanatory comments to reflect the new constraint.

4. Rebuild and verify source analysis actually works

A green compile is not sufficient — the Analysis API fails at runtime, not compile time.

• ./gradlew :core:build — compiles and runs core tests, including SourceAnalyzer tests.
• Run the analyzer end-to-end on a real library so type resolution is exercised, e.g. fetch a known library via the MCP tools (fetch_library then get_api_signature / get_kdoc) and confirm signatures resolve types (not just PSI text fallback).
• Watch for NoSuchMethodError / NoClassDefFoundError / immutable-collections shadowing — those signal a coupled-pin mismatch, not a code bug. Revisit step 2.

5. Report

Summarize: old → new Kotlin version, which coupled pins moved (and why, with the official source), whether the coroutines-intellij fork is still needed, and the verification evidence (test result + a resolved signature from a fetched library). Note anything that degraded to PSI-only fallback. Do not commit unless asked.