Skip to content

rsicarelli/fakt / .claude/skills/kotlin-api-consultant

kotlin-api-consultant

Verified

Checks Kotlin compiler API usage against the Kotlin versions Fakt supports — which path runs on which compiler, how compat shims are written, how to verify across versions, and how to bump Kotlin. Use when calling a new FIR/IR/compiler-plugin API, seeing NoSuchMethodError, NoSuchFieldError or NoClassDefFoundError from compiler classes, bumping the Kotlin version, or checking whether an API exists in the minimum supported Kotlin. Make sure to use this skill whenever compiler plugin code starts using a Kotlin compiler API it didn't use before — these APIs change between Kotlin releases and a break only shows up on an older supported version.

FileKindSize
SKILL.mdskill md3.6 KB
---
name: kotlin-api-consultant
description: Checks Kotlin compiler API usage against the Kotlin versions Fakt supports — which path runs on which compiler, how compat shims are written, how to verify across versions, and how to bump Kotlin. Use when calling a new FIR/IR/compiler-plugin API, seeing NoSuchMethodError, NoSuchFieldError or NoClassDefFoundError from compiler classes, bumping the Kotlin version, or checking whether an API exists in the minimum supported Kotlin. Make sure to use this skill whenever compiler plugin code starts using a Kotlin compiler API it didn't use before — these APIs change between Kotlin releases and a break only shows up on an older supported version.
allowed-tools: Read, Grep, Glob, Bash, WebFetch
---

# Kotlin API Consultant

Keeps Fakt's compiler plugin working across every Kotlin version in the support matrix.

## Instructions

### 1. Know Which Compiler Runs the Code

- **Supported range:** the matrix in `docs/compatibility.md` is the source of truth (minimum and latest tested).
- **Build:** `compiler/` compiles `compileOnly` against `kotlin-compiler-embeddable` at the `kotlin` version in `gradle/libs.versions.toml`.
- **Default FIR path** (`FaktGenerateTask` worker): runs on the compiler Fakt pins — `FAKT_KOTLIN_VERSION` in `gradle-plugin/.../FaktGradleSubplugin.kt`. The user's Kotlin version doesn't matter here.
- **Legacy in-process path** (Native mains, `LEGACY`, or `-Pfakt.useExperimentalGenerateTask=false`): runs inside the user's own compiler, which can be as old as the minimum supported version.

So code reachable from the in-process path (the `ir/` package, `FaktCompilerPluginRegistrar`, and the FIR checkers it registers) must only use APIs present in every supported version.

### 2. Check the API Across the Range

Look the API up at the minimum and latest supported versions in the Kotlin repository (tags like `v2.2.0`), not just the version on the build classpath. Signs of trouble:

- The symbol doesn't exist at the minimum version, or its signature differs
- `@Deprecated(level = ERROR)`, or a replacement API introduced after the minimum
- An opt-in annotation (`@ExperimentalCompilerApi`, `@UnsafeApi`) the module doesn't already opt into

### 3. Bridge Differences with a Compat Shim

When the API differs across the range, isolate it in a small private helper suffixed `Compat`, next to its call site. Existing patterns:

- `FaktCompilerPluginRegistrar.registerExtensionCompat` — calls `registerExtension` reflectively; Kotlin 2.4.0 widened its receiver type, and a direct call compiled against 2.4 fails with `NoClassDefFoundError` on 2.2–2.3
- `FirToIrTransformer.extensionReceiverParameterCompat` — reads the extension receiver from the unified `parameters` list instead of the deprecated `extensionReceiverParameter`

Keep the shim's KDoc explaining which versions differ, so it can be deleted when the minimum moves past them.

### 4. Verify on Every Supported Version

```bash
make test-compat-all          # publish-local + jvmTest on every samples/compat/kotlin-*/
make test-compat-2.2.0        # one version
```

CI runs the same matrix (version list in `.github/workflows/development.yml`) through `.github/actions/test-compat-samples`.

### 5. Bumping Kotlin

Update `kotlin` in `gradle/libs.versions.toml` **and** `FAKT_KOTLIN_VERSION` (nothing checks that they match), add a `samples/compat/kotlin-<version>/` sample and its entry in `development.yml`, and update `docs/compatibility.md`.

## Related Skills

- **`compilation`** — Diagnose the build failure that surfaced the API problem
- **`codegen`** — Code generation, which doesn't touch compiler APIs
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall