Migrating from K1

Once an IntelliJ plugin has been migrated to the Analysis API, it will need to declare its compatibility with the K2 Kotlin mode in the plugin.xml. Otherwise, the plugin will not be loaded when the K2 mode is active.

Analysis Entry Point

// Simply returns a 'BindingContext' containing "certain" information about the element
fun KtElement.analyze(bodyResolveMode: BodyResolveMode): BindingContext

// Returns the semantic declaration abstraction, calls 'analyze()' under the hood
fun KtDeclaration.resolveToDescriptorIfAny(bodyResolveMode: BodyResolveMode): DeclarationDescriptor?

// Returns the resolved call information, also delegates to 'analyze()'
fun KtElement.resolveToCall(bodyResolveMode: BodyResolveMode): ResolvedCall<out CallableDescriptor>?

These are not the only ones available – there are numerous more sophisticated ones, including analyzeWithAllCompilerChecks(), analyzeWithContent(), analyzeInContext(), and others.

In contrast, the Analysis API offers a single analyze {} entry point. Most of the API surface is accessible inside the lambda, including the symbol extension property that maps a KtDeclaration to its symbol:

analyze(declaration) {
    // 'KaSymbol' is similar to 'DeclarationDescriptor'
    val symbol: KaSymbol = declaration.symbol
}

While this change might seem like a significant new restriction, it actually has always been in place. Careless handling of BindingContext and its contents was often a source of exceptions, incorrect behavior, and leaks. Therefore, the new API naturally guides you on how to analyze the code correctly.

Declarations

Both the old compiler API and the Analysis API are built on top of PsiElement, the API in IntelliJ IDEA responsible for creating syntax trees. However, unlike some other language implementations, Kotlin distinctly separates PSI and semantic declaration representation. Refer to the Symbols vs. PSI section for additional information.

In the old compiler, this semantic representation is called DeclarationDescriptor. There are specific interfaces for each declaration type, including ClassDescriptor, FunctionDescriptor, and PropertyDescriptor. Descriptors are obtained from a BindingContext:

val descriptor: DeclarationDescriptor =
    bindingContext[BindingContext.DECLARATION_TO_DESCRIPTOR, declaration]

In the Analysis API, a concept similar to descriptors is named KaSymbol. Just like descriptors, there are KaClassSymbol, KaFunctionSymbol, and KaPropertySymbol.

To get a symbol for a KtDeclaration, simply use the symbol extension property. symbol is overloaded for subtypes of KaSymbol, meaning that if you call it on some specific declaration type, you will get a more precise symbol type. For instance:

val property: KtProperty = ...

analyze(property) {
    val symbol = property.symbol
    // symbol is a 'KaPropertySymbol'
}

For a KtClassOrObject, however, symbol will return just a KaDeclarationSymbol. The reason for this is Kotlin PSI's legacy: A KtEnumEntry is a subtype of KtClassOrObject, whereas in K2, an enum entry is a variable. So, you may wish to use ktClassOrObject.classSymbol instead, as it will return a KaClassSymbol?.

Declaration Names

In the old compiler, FqName was often used to store fully-qualified declaration names. Although it is a straightforward abstraction, FqName cannot differentiate between package and classifier components. For instance, in foo.Bar.Baz, Bar could either be a package or an outer class name. While Kotlin's coding conventions discourage capitalized package names, technically it remains possible. Consequently, the Analysis API employs a different abstraction for storing qualified names, namely ClassId for classes and CallableId for functions and properties.

To construct a ClassId, merely pass its text representation to ClassId.fromString(). The slashes / separate package components, whereas dots . distinguish nested class names.

val intClassId = ClassId.fromString("kotlin/Int")
val nestedClassId = ClassId.fromString("foo/bar/Outer.Nested")

The StandardClassIds class provides ClassIds for many common class names from the Kotlin standard library.

You can construct a CallableId by supplying either an outer ClassId or a package FqName and a callable name.

val suspendCallableId = CallableId(FqName("kotlin"), Name.identifier("suspend"))
val equalsCallableId = CallableId(ClassId("kotlin/Any"), Name.identifier("equals"))

Calls and references

The old API offered a single ResolveCall class that represented all kinds of calls (successful and error calls, simple and compound calls). For compound calls, ResolveCall itself represents only one of calls, while additional data was available in quite obscure places, like CallTransformer.CallForImplicitInvoke.

Resolving a reference

Old API: bindingContext[BindingContext.REFERENCE_TARGET, referenceExpression]

Analysis API: referenceExpression.mainReference.resolveToSymbol()

Resolving a successful call

Old API: expression.getResolvedCall(bindingContext)?.takeIf { it.isReallySuccess() }

Analysis API: expression.resolveToCall().successfulCallOrNull()

Getting parameter-argument mapping

Old API:

val call = unaryExpression.getResolvedCall(bindingContext) ?: return
call.valueArguments

Analysis API:

val call = expression.resolveToCall()?.successfulFunctionCallOrNull() ?: return
call.argumentMapping

Getting dispatch and extension receivers

Old API:

val call: ResolvedCall<*> = ...
operatorCall.dispatchReceiver
operatorCall.extensionReceiver

Analysis API:

val call: KaCallableMemberCall<*, *> = ...
call.partiallyAppliedSymbol.dispatchReceiver
call.partiallyAppliedSymbol.extensionReceiver

Example

Using the old compiler API

val SPECIAL_ANNOTATION_NAME = FqName("my.app.Special")

fun hasAnnotation(declaration: KtDeclaration): Boolean {
    val bindingContext = declaration.analyze()
    val descriptor = bindingContext[BindingContext.DECLARATION_TO_DESCRIPTOR, declaration]
        ?: return false

    return descriptor.annotations.hasAnnotation(SPECIAL_ANNOTATION_NAME)
}

Using Analysis API

val SPECIAL_ANNOTATION_CLASS_ID = ClassId.fromString("my/app/Special")

fun hasAnnotation(declaration: KtDeclaration): Boolean {
    analyze(declaration) {
        return SPECIAL_ANNOTATION_CLASS_ID in declaration.symbol.annotations
    }
}

Migrating from K1﻿

The Conceptual Difference﻿

Analysis Entry Point﻿

Declarations﻿

Declaration Names﻿

Classes﻿

Functions﻿

Variables﻿

Calls and references﻿

Types﻿

Misc﻿

Example﻿

Using the old compiler API﻿

Using Analysis API﻿

Migrating from K1

The Conceptual Difference

Analysis Entry Point

Declarations

Declaration Names

Classes

Functions

Variables

Calls and references

Types

Misc

Example

Using the old compiler API

Using Analysis API