# Low Level API

Low-level API (LL API for short) is an interlayer between Analysis API FIR Implementation and FIR compiler. Low-level API is responsible for:

* Finding corresponding `FirElement` by `KtElement`
* Lazy resolving of `FirDeclaration`
* Collecting diagnostics for `FirDeclaration`
* Incremental code analysis
* Implementing FIR providers using IntelliJ indexes

You can read about how FIR compiler works [here](../../fir/fir-basics.md).

The entry point for LL API is `FirModuleResolveState`.` FirModuleResolveState` is a view of project modules visible from the current module.
The lifetime of
`FirModuleResolveState` is limited by Kotlin Out of Block Modification.

## Mapping KtElement to FirElement (KT -> FIR) & Incremental Analysis

To implement some stuff in Analysis API, we need to get resolved `FirElement` by the given `KtElement`. Also, this functionality is
considered to be used not very often (mostly, for the files opened in the editor) as it resolves declarations to the `BODY_RESOLVE` and
collects `KT -> FIR` mappings for it.

Finding `KT -> FIR` mappings works like the following:

* For every `KtFile` we need mapping for, we have `FileStructure` which contains a tree like-structure of `FileStructureElement`
* `FileStructureElement` can be one of the following:
    * `ReanalyzableStructureElement` represents a non-local declaration that can be incrementally reanalyzed after non-out of block change
      inside it.
    * `NonReanalyzableDeclarationStructureElement` represents non-local declaration which can not be incrementally reanalyzed
    * `RootFileStructureElement` represents file except all declarations inside
* `FileStructureElement` form a nested tree-like structure
* Then we want to get `KT -> FIR` mapping we find containing `FileStructureElement`. If is not up-to-date we rebuild it and then take from
  it.

The following declarations can be reanalyzed (in other words, can be represented as ReanalyzableStructureElement):

* Functions with explicit return type
* Properties with explicit type
* Secondary constructors
* Getters/setters of the property with explicit type

# Lazy Declaration resolving

FIR in compiler mode works by sequentially running every resolve phase on all files at once like shown in pseudo-code:

```kotlin
for (phase in allResolvePhases) {
    for (file in allFirFiles) {
        runPhaseOnFile(file, phase)
    }
}
```

Such behavior does not work for the Analysis API. Analysis API needs to resolve one specific declaration to the minimum possible phase. To
solve that problem, there are *lazy phases*. Lazy phases can be run only on a single declaration, not on the whole `FirFile`.

Suppose we need to resolve some `FirDeclaration` to phase number `N`:

* First, we resolve containing `FirFile` to the `IMPORTS` phase,
* Then we resolve file annotations,
* When we find a non-local container for our declaration as only non-local declarations can be lazily resolved for now,
* Finally, resolve *only* that container from phase number `1` to phase `N`

All resolve happens under containing file-based *write lock*.

## Project Module Structure

The `FirModuleResolveState` represents a view from a specific module (**root module**) to the dependent modules. A module is represented by:

* `FirIdeSourcesSession` the implementation of `FirSession` (FIR compiler representation of a module)
* `ModuleFileCache` the `KtFile -> FirFile` cache & also caches for FIR providers