Как KSP моделирует код Kotlin

Типы и разрешение

На разрешение приходится большая часть затрат на реализацию базового API. Поэтому ссылки на типы спроектированы так, чтобы процессоры разрешали их явно (за некоторыми исключениями). Когда упоминается тип (например, KSFunctionDeclaration.returnType или KSAnnotation.annotationType), это всегда KSTypeReference, то есть KSReferenceElement с аннотациями и модификаторами.

interface KSFunctionDeclaration : ... {
  val returnType: KSTypeReference?
  // ...
}

interface KSTypeReference : KSAnnotated, KSModifierListOwner {
  val type: KSReferenceElement
}

KSTypeReference можно разрешить в KSType, который ссылается на тип в системе типов Kotlin.

У KSTypeReference есть KSReferenceElement, моделирующий структуру программы Kotlin, а именно то, как записана ссылка. Он соответствует элементу type в грамматике Kotlin.

KSReferenceElement может быть KSClassifierReference или KSCallableReference, которые содержат много полезной информации и не требуют разрешения. Например, у KSClassifierReference есть referencedName, а у KSCallableReference — receiverType, functionArguments и returnType.

Если требуется исходное объявление, на которое ссылается KSTypeReference, обычно его можно найти, разрешив ссылку в KSType и обратившись к нему через KSType.declaration. Переход от места упоминания типа к месту объявления его класса выглядит так:

val ksType: KSType = ksTypeReference.resolve()
val ksDeclaration: KSDeclaration = ksType.declaration

Разрешение типов требует значительных затрат, поэтому оно выполняется явно. Часть информации, получаемой в результате разрешения, уже доступна в KSReferenceElement. Например, KSClassifierReference.referencedName позволяет отфильтровать множество неинтересующих элементов. Разрешайте тип только в том случае, если вам нужны конкретные сведения из KSDeclaration или KSType.

KSTypeReference, указывающий на тип функции, содержит большую часть информации в своём элементе. Его можно разрешить в семейство Function0, Function1 и так далее, однако такое разрешение не даёт больше информации, чем KSCallableReference. Один из случаев, когда требуется разрешать ссылки на типы функций, — работа с идентификатором прототипа функции.