0
# Kotlin Scripting IDE Services
1

2
Kotlin Scripting IDE Services is a compiler extension that provides intelligent code completion and static analysis capabilities for Kotlin scripting environments. It extends the Kotlin compiler with specialized functionality for interactive development environments, enabling features like intelligent code completion, static analysis, and error detection in Kotlin script files.
3

4
## Package Information
5

6
- **Package Name**: kotlin-scripting-ide-services
7
- **Package Type**: Maven (Gradle)
8
- **Language**: Kotlin
9
- **Installation**: `implementation("org.jetbrains.kotlin:kotlin-scripting-ide-services:2.2.0")`
10

11
## Core Imports
12

13
```kotlin
14
import org.jetbrains.kotlin.scripting.ide_services.compiler.KJvmReplCompilerWithIdeServices
15
import org.jetbrains.kotlin.scripting.ide_services.compiler.ReplCompletionOptionsBuilder
16
import org.jetbrains.kotlin.scripting.ide_services.compiler.filterOutShadowedDescriptors
17
import org.jetbrains.kotlin.scripting.ide_services.compiler.nameFilter
18
import kotlin.script.experimental.api.*
19
import kotlin.script.experimental.jvm.defaultJvmScriptingHostConfiguration
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import org.jetbrains.kotlin.scripting.ide_services.compiler.KJvmReplCompilerWithIdeServices
26
import kotlin.script.experimental.api.*
27
import kotlin.script.experimental.jvm.defaultJvmScriptingHostConfiguration
28

29
// Create a REPL compiler with IDE services
30
val compiler = KJvmReplCompilerWithIdeServices(defaultJvmScriptingHostConfiguration)
31

32
// Prepare script code and cursor position
33
val sourceCode = """
34
    val x = 10
35
    val y = 20
36
    x + y.
37
""".trimIndent()
38

39
val cursor = SourceCode.Position(2, 6) // After the dot
40

41
// Get code completions
42
val completionResult = compiler.complete(
43
    sourceCode.toScriptSource(),
44
    cursor,
45
    ScriptCompilationConfiguration()
46
)
47

48
// Analyze code for errors and type information
49
val analysisResult = compiler.analyze(
50
    sourceCode.toScriptSource(),
51
    cursor,
52
    ScriptCompilationConfiguration()
53
)
54
```
55

56
## Architecture
57

58
Kotlin Scripting IDE Services is built around several key components:
59

60
- **Embeddable Package**: The main package (`scripting-ide-services-embeddable`) that includes all dependencies for standalone use
61
- **Core IDE Services**: Primary completion and analysis functionality (`scripting-ide-services`)
62
- **Common Utilities**: Shared IDE utilities and resolution helpers (`scripting-ide-common`)
63
- **REPL Integration**: Specialized compiler integration for REPL environments with stateless analysis
64
- **Resolution System**: Kotlin compiler integration for symbol resolution and type inference
65

66
## Capabilities
67

68
### REPL Compiler with IDE Services
69

70
Main compiler class that provides both code completion and static analysis for Kotlin scripts in REPL environments. Supports embeddable usage and advanced completion configuration.
71

72
```kotlin { .api }
73
class KJvmReplCompilerWithIdeServices(
74
    hostConfiguration: ScriptingHostConfiguration = defaultJvmScriptingHostConfiguration
75
) : ReplCompleter, ReplCodeAnalyzer
76

77
interface ReplCompleter {
78
    suspend fun complete(
79
        snippet: SourceCode,
80
        cursor: SourceCode.Position,
81
        configuration: ScriptCompilationConfiguration
82
    ): ResultWithDiagnostics<ReplCompletionResult>
83
}
84

85
interface ReplCodeAnalyzer {
86
    suspend fun analyze(
87
        snippet: SourceCode,
88
        cursor: SourceCode.Position,
89
        configuration: ScriptCompilationConfiguration
90
    ): ResultWithDiagnostics<ReplAnalyzerResult>
91
}
92
```
93

94
[REPL Compiler Services](./repl-compiler.md)
95

96
### Completion Configuration
97

98
Configuration system for customizing code completion behavior including shadowed descriptor filtering and name filtering options.
99

100
```kotlin { .api }
101
interface ReplCompletionOptionsKeys
102

103
open class ReplCompletionOptionsBuilder : PropertiesCollection.Builder(), ReplCompletionOptionsKeys
104

105
fun ReplCompletionOptionsBuilder.filterOutShadowedDescriptors(value: Boolean)
106
fun ReplCompletionOptionsBuilder.nameFilter(value: (String, String) -> Boolean)
107

108
val ReplCompletionOptionsKeys.filterOutShadowedDescriptors: Boolean
109
val ReplCompletionOptionsKeys.nameFilter: (String, String) -> Boolean
110
```
111

112
[Completion Configuration](./completion-config.md)
113

114
### Resolution and Reference Services  
115

116
Core resolution services providing symbol resolution, reference finding, and IDE-like analysis capabilities for Kotlin scripts.
117

118
```kotlin { .api }
119
interface ResolutionFacade {
120
    val project: Project
121
    val moduleDescriptor: ModuleDescriptor
122
    
123
    fun analyzeWithAllCompilerChecks(
124
        elements: Collection<KtElement>,
125
        callback: DiagnosticSink.DiagnosticsCallback? = null
126
    ): AnalysisResult
127
}
128

129
class ReferenceVariantsHelper(
130
    bindingContext: BindingContext,
131
    resolutionFacade: ResolutionFacade,
132
    moduleDescriptor: ModuleDescriptor,
133
    visibilityFilter: (DeclarationDescriptor) -> Boolean
134
) {
135
    fun getReferenceVariants(
136
        expression: KtSimpleNameExpression,
137
        kindFilter: DescriptorKindFilter,
138
        nameFilter: (Name) -> Boolean
139
    ): Collection<DeclarationDescriptor>
140
}
141
```
142

143
[Resolution Services](./resolution.md)
144

145
### Call Type Detection
146

147
Advanced call context analysis for determining the type of call being made and appropriate completion suggestions.
148

149
```kotlin { .api }
150
sealed class CallType<TReceiver : KtElement?>
151

152
sealed class CallTypeAndReceiver<TReceiver : KtElement?, out TCallType : CallType<TReceiver>> {
153
    companion object {
154
        fun detect(expression: KtSimpleNameExpression): CallTypeAndReceiver<*, *>
155
    }
156
}
157

158
data class ReceiverType(
159
    val type: KotlinType,
160
    val receiverIndex: Int,
161
    val implicitValue: ReceiverValue?
162
)
163
```
164

165
[Call Type Detection](./call-types.md)
166

167
### Utility Classes and Extensions
168

169
Various utility classes for filtering, type handling, and descriptor management in IDE contexts.
170

171
```kotlin { .api }
172
class ShadowedDeclarationsFilter(
173
    bindingContext: BindingContext,
174
    resolutionFacade: ResolutionFacade,
175
    context: PsiElement,
176
    explicitReceiverValue: ReceiverValue?
177
) {
178
    fun <TDescriptor : DeclarationDescriptor> filter(
179
        declarations: Collection<TDescriptor>
180
    ): Collection<TDescriptor>
181
}
182

183
class FuzzyType(
184
    type: KotlinType,
185
    freeParameters: Collection<TypeParameterDescriptor>
186
)
187

188
object IdeDescriptorRenderersScripting
189
```
190

191
[Utilities](./utilities.md)
192

193
## Types
194

195
### Core Result Types
196

197
```kotlin { .api }
198
typealias ReplCompletionResult = Sequence<SourceCodeCompletionVariant>
199

200
class ReplAnalyzerResult(baseConfigurations: Iterable<ReplAnalyzerResult>, body: Builder.() -> Unit = {}) :
201
    PropertiesCollection(Builder(baseConfigurations).apply(body).data) {
202

203
    constructor(body: Builder.() -> Unit = {}) : this(emptyList(), body)
204

205
    class Builder internal constructor(baseConfigurations: Iterable<ReplAnalyzerResult>) :
206
        ReplAnalyzerResultKeys,
207
        PropertiesCollection.Builder(baseConfigurations)
208

209
    companion object : ReplAnalyzerResultKeys
210
}
211

212
interface ReplAnalyzerResultKeys
213

214
val ReplAnalyzerResultKeys.analysisDiagnostics: Sequence<ScriptDiagnostic>
215
val ReplAnalyzerResultKeys.renderedResultType: String?
216

217
data class SourceCodeCompletionVariant(
218
    val text: String,
219
    val displayText: String,
220
    val tail: String,
221
    val icon: String,
222
    val deprecationLevel: DeprecationLevel? = null
223
)
224
```
225

226
### Analysis Results
227

228
```kotlin { .api }
229
data class AnalyzeWithCursorResult(
230
    val ktScript: KtFile,
231
    val bindingContext: BindingContext,
232
    val resolutionFacade: KotlinResolutionFacadeForRepl,
233
    val moduleDescriptor: ModuleDescriptor,
234
    val cursorAbs: Int,
235
    val resultProperty: PropertyDescriptor?
236
)
237

238
interface ReplLineAnalysisResultWithStateless {
239
    data class Stateless(
240
        val bindingContext: BindingContext,
241
        val resolutionFacade: KotlinResolutionFacadeForRepl,
242
        val moduleDescriptor: ModuleDescriptor,
243
        val resultProperty: PropertyDescriptor?
244
    ) : ReplLineAnalysisResultWithStateless
245
}
246
```
247

248
### Configuration Types
249

250
```kotlin { .api }
251
interface PropertiesCollection {
252
    interface Key<T>
253
    
254
    abstract class Builder(baseConfigurations: Iterable<PropertiesCollection>) {
255
        protected val data: MutableMap<Key<*>, Any?>
256
        
257
        constructor() : this(emptyList())
258
        
259
        operator fun <T> set(key: Key<T>, value: T)
260
        operator fun <T> get(key: Key<T>): T?
261
    }
262
}
263

264
interface ScriptingHostConfiguration : PropertiesCollection
265
interface ScriptCompilationConfiguration : PropertiesCollection
266
interface SourceCode {
267
    val text: String
268
    val name: String?
269
    val locationId: String?
270
    
271
    data class Position(val line: Int, val col: Int)
272
}
273

274
interface ResultWithDiagnostics<out T> {
275
    val value: T?
276
    val diagnostics: List<ScriptDiagnostic>
277
}
278
```