In-memory file analysis

In most cases, source files — whether written by a user or auto-generated — are stored on disk and belong to a specific module. The build system understands the project layout and instructs the compiler or the IDE to use appropriate dependencies for all files in that module. For script files, such as build.gradle.kts, the situation is more complex since scripts technically do not belong to any module. However, in such cases, the build system also provides the necessary context. For example, Gradle build scripts include the Gradle API and all libraries Gradle depends on in their classpath.

In certain cases, it might be useful to analyze a file without storing it in the file system. For example, an IDE inspection may use in-memory files to verify whether code will remain valid after applying a proposed change. Specifically, the inspection might create a copy of the KtFile, apply the change to the copy, and check for new compilation errors. In such scenarios, the inspection needs to supply the correct analysis context for the in-memory KtFile.

Stand-alone file analysis

To create a file, we use the KtPsiFactory class:

val text =
    """
    package test

    fun foo() {
        println("Hello, world!")
    }
    """.trimIndent()

val factory = KtPsiFactory(project)
val file = factory.createFile(text)

KtPsiFactory offers many utilities for creating chunks of Kotlin code. In our case, we are primarily interested in creating entire Kotlin files.

If we analyze the file we created using analyze {}, we notice that the println reference is reported as unresolved:

analyze(file) {
    val diagnostics = file.collectDiagnostics(KaDiagnosticCheckerFilter.ONLY_COMMON_CHECKERS)
    // ["Unresolved reference 'println'."]
    val messages = diagnostics.map { it.defaultMessage }
}

This happens because the KtFile we created lacks any attached context, making the Kotlin Standard Library unavailable. However, code in the file still can access a few basic Kotlin types, such as Int or String, and can resolve references to declarations from the same file.

Now, let's assume we have a contextFile that belongs to a module and want to analyze our in-memory file as it was in that module. First, we retrieve the containing module of the contextFile.

val contextModule = KaModuleProvider.getModule(project, contextFile, useSiteModule = null)

@OptIn(KaExperimentalApi::class)
file.contextModule = contextModule

The created file can reference declarations from the context module, including internal ones. However, no matter the content of our newly created file, it will not affect resolution of our context file. Such as, if we declare a function in the file, it will not be visible from the contextFile.

val text =
    """
    package test

    fun foo() {
        println("Hello, world!")
    }
    """.trimIndent()

val factory = KtPsiFactory(project)
val file = factory.createFile(text)

val contextModule = KaModuleProvider.getModule(project, contextFile, useSiteModule = null)

@OptIn(KaExperimentalApi::class)
file.contextModule = contextModule

analyze(file) {
    val diagnostics = file.collectDiagnostics(KaDiagnosticCheckerFilter.ONLY_COMMON_CHECKERS)
    // An empty list
    val messages = diagnostics.map { it.defaultMessage }
}

Context modules

In the previous example, we used the KaModuleProvider.getModule() function to retrieve the module containing the contextFile. The returned value is of type KaModule which is an Analysis API abstraction over Module, Library, and Sdk concepts from IntelliJ IDEA. Specifically, a KaSourceModule represents a source module, and libraries and SDKs are represented by KaLibraryModules. Every KaSymbol in the Analysis API is associated with some KaModule.

If you already have a reference to a Module, you can convert it to a KaModule using one of the Kotlin plugin helper functions:

fun Module.toKaSourceModule(kind: KaSourceModuleKind): KaSourceModule?
fun Module.toKaSourceModuleForProduction(): KaSourceModule?
fun Module.toKaSourceModuleForTest(): KaSourceModule?

For more related APIs, refer to the Kotlin plugin's source code. There are also overloads that accept ModuleId and ModuleEntity from the newer project model API.

In the KaModuleProvider.getModule function call, we passed useSiteModule = null. For advanced scenarios, you might want to analyze files from other modules in the context of a synthetic module. In such cases, that synthetic module can be passed as a useSiteModule. For typical use cases, it is safe to pass null.

Physical and non-physical files

In the previous example, we used the KtPsiFactory to create a non-physical file. From IntelliJ IDEA's perspective, "non-physical" differs from whether the file is stored on disk. We can create both physical and non-physical KtFiles that are not written to the disk.

If you need a long-lived file that will be modified and analyzed multiple times, you should create a physical file by using a KtPsiFactory with eventSystemEnabled = true:

val factory = KtPsiFactory(project, eventSystemEnabled = true)
val file = factory.createFile(text)

File copies

To create a copy of a file, you can use the copy function:

val fileCopy = file.copy() as KtFile

The copy() function sets a reference to the original file in the produced copy. As a result, the getOriginalFile() of the newly created file points back to the original file. This allows the Analysis API to automatically use the context of the original file. In other words, there is no need to manually set the contextModule for a copied file.

The copy() function creates non-physical files. For this setup (a non-physical file with a getOriginalFile() set), the Analysis API uses a different analysis strategy by default.

If you make changes to the declaration signatures in the copied file, you should analyze it independently of the original file. To do so, use the PREFER_SELF resolution mode with the analyzeCopy() function:

analyzeCopy(fileCopy, KaDanglingFileResolutionMode.PREFER_SELF) {
    // Analysis code, just as in `analyze()`
}

On the other side, if you manually create a physical file copy, you can still request more efficient analysis by passing the KaDanglingFileResolutionMode.IGNORE_SELF option:

val factory = KtPsiFactory(file.project, eventSystemEnabled = true)
val fileCopy = factory.createFile("text.kt", originalFile.text)
fileCopy.originalFile = file

analyzeCopy(fileCopy, KaDanglingFileResolutionMode.IGNORE_SELF) {
    // Analysis code, just as in `analyze()`
}

The analyzeCopy() function works exclusively for file copies. Unless you need to configure the resolution mode explicitly, use the usual analyze() instead.

Code fragments

All three types of code fragments extend the KtCodeFragment class, which itself extends KtFile.

Code fragments differ from typical KtFiles in several important ways:

To create a code fragment, you need two inputs: the source text of the fragment and a context element from the surrounding code. For example, consider the following code snippet where print(name) is a context element:

fun test() {
    val name = "poem.txt"
    print(name)
}

Now, let's create a code fragment that references name to read from a file:

val fragment = KtExpressionCodeFragment(
    project,
    name = "fragment.kt",
    text = "File(name).readText()",
    context = contextElement,
    imports = listOf("java.io.File")
)

A code fragment can reference any declaration visible from its context element, including local declarations. For the above example, the code fragment accesses the local variable name.

If we pass the val name = "poem.txt" declaration as a context element, the code fragment analysis will result in an error, as variables are not yet available on the line of their declaration.

Since code fragments extend KtFile, you can analyze them in the same way as you analyze files:

analyze(fragment) {
    // Analysis code
}

In-memory file analysis﻿

note

Stand-alone file analysis﻿

Context modules﻿

Physical and non-physical files﻿

File copies﻿