0
# REPL Compiler Services
1

2
Main compiler class providing intelligent code completion and static analysis for Kotlin scripts in REPL environments.
3

4
## Capabilities
5

6
### KJvmReplCompilerWithIdeServices
7

8
The primary entry point for REPL compilation with IDE services. Provides both completion and analysis capabilities with full compiler integration.
9

10
```kotlin { .api }
11
/**
12
 * JVM REPL compiler with IDE services providing completion and analysis
13
 * @param hostConfiguration - Scripting host configuration, defaults to defaultJvmScriptingHostConfiguration
14
 */
15
class KJvmReplCompilerWithIdeServices(
16
    hostConfiguration: ScriptingHostConfiguration = defaultJvmScriptingHostConfiguration
17
) : KJvmReplCompilerBase<IdeLikeReplCodeAnalyzer>, ReplCompleter, ReplCodeAnalyzer
18
```
19

20
**Usage Example:**
21

22
```kotlin
23
import org.jetbrains.kotlin.scripting.ide_services.compiler.KJvmReplCompilerWithIdeServices
24
import kotlin.script.experimental.jvm.defaultJvmScriptingHostConfiguration
25

26
// Create compiler with default configuration
27
val compiler = KJvmReplCompilerWithIdeServices()
28

29
// Create compiler with custom host configuration
30
val customConfig = ScriptingHostConfiguration {
31
    jvm {
32
        // Custom JVM configuration
33
    }
34
}
35
val customCompiler = KJvmReplCompilerWithIdeServices(customConfig)
36
```
37

38
### Code Completion
39

40
Provides intelligent code completion with context-aware suggestions, type information, and filtering options.
41

42
```kotlin { .api }
43
/**
44
 * Provides code completion at the specified cursor position
45
 * @param snippet - Source code to analyze
46
 * @param cursor - Cursor position for completion
47
 * @param configuration - Script compilation configuration
48
 * @returns ResultWithDiagnostics containing completion results
49
 */
50
suspend fun complete(
51
    snippet: SourceCode,
52
    cursor: SourceCode.Position,
53
    configuration: ScriptCompilationConfiguration
54
): ResultWithDiagnostics<ReplCompletionResult>
55
```
56

57
**Usage Examples:**
58

59
```kotlin
60
// Basic completion
61
val sourceCode = """
62
    val list = listOf(1, 2, 3)
63
    list.
64
""".trimIndent()
65

66
val cursor = SourceCode.Position(1, 5) // After the dot
67
val completions = compiler.complete(
68
    sourceCode.toScriptSource(),
69
    cursor,
70
    ScriptCompilationConfiguration()
71
)
72

73
when (completions) {
74
    is ResultWithDiagnostics.Success -> {
75
        completions.value.completions.forEach { variant ->
76
            println("${variant.displayText} - ${variant.tail}")
77
        }
78
    }
79
    is ResultWithDiagnostics.Failure -> {
80
        completions.reports.forEach { diagnostic ->
81
            println("Error: ${diagnostic.message}")
82
        }
83
    }
84
}
85

86
// Completion with configuration
87
val config = ScriptCompilationConfiguration {
88
    completion {
89
        filterOutShadowedDescriptors(false)
90
        nameFilter { name, prefix -> name.contains(prefix, ignoreCase = true) }
91
    }
92
}
93

94
val advancedCompletions = compiler.complete(sourceCode.toScriptSource(), cursor, config)
95
```
96

97
### Code Analysis
98

99
Performs static analysis of Kotlin script code, providing error detection, type inference, and diagnostic information.
100

101
```kotlin { .api }
102
/**
103
 * Analyzes script code at the specified cursor position
104
 * @param snippet - Source code to analyze
105
 * @param cursor - Cursor position for analysis
106
 * @param configuration - Script compilation configuration
107
 * @returns ResultWithDiagnostics containing analysis results
108
 */
109
suspend fun analyze(
110
    snippet: SourceCode,
111
    cursor: SourceCode.Position,
112
    configuration: ScriptCompilationConfiguration
113
): ResultWithDiagnostics<ReplAnalyzerResult>
114
```
115

116
**Usage Examples:**
117

118
```kotlin
119
// Basic analysis  
120
val sourceCode = """
121
    val x: String = 42  // Type error
122
    val y = x.length
123
""".trimIndent()
124

125
val cursor = SourceCode.Position(1, 10)
126
val analysis = compiler.analyze(
127
    sourceCode.toScriptSource(),
128
    cursor,
129
    ScriptCompilationConfiguration()
130
)
131

132
when (analysis) {
133
    is ResultWithDiagnostics.Success -> {
134
        val result = analysis.value
135
        println("Is complete: ${result.isComplete}")
136
        result.renderedResultType?.let { type ->
137
            println("Result type: $type")
138
        }
139
        
140
        result.analysisDiagnostics.forEach { diagnostic ->
141
            println("${diagnostic.severity}: ${diagnostic.message}")
142
        }
143
    }
144
    is ResultWithDiagnostics.Failure -> {
145
        analysis.reports.forEach { diagnostic ->
146
            println("Analysis error: ${diagnostic.message}")
147
        }
148
    }
149
}
150
```
151

152
### Internal Analysis Components
153

154
The compiler uses several internal components for advanced analysis:
155

156
```kotlin { .api }
157
/**
158
 * Internal analysis result containing detailed resolution information
159
 */
160
data class AnalyzeWithCursorResult(
161
    val ktScript: KtFile,
162
    val bindingContext: BindingContext,
163
    val resolutionFacade: KotlinResolutionFacadeForRepl,
164
    val moduleDescriptor: ModuleDescriptor,
165
    val cursorAbs: Int,
166
    val resultProperty: PropertyDescriptor?
167
)
168
```
169

170
### Core Implementation Classes
171

172
These internal classes provide the underlying functionality but are part of the public API:
173

174
```kotlin { .api }
175
/**
176
 * Code analyzer providing IDE-like analysis for REPL contexts
177
 */
178
class IdeLikeReplCodeAnalyzer(
179
    environment: KotlinCoreEnvironment,
180
    implicitsResolutionFilter: ImplicitsExtensionsResolutionFilter
181
) : ReplCodeAnalyzerBase<IdeLikeReplCodeAnalyzer.ReplLineAnalysisResultWithStateless> {
182
    
183
    fun statelessAnalyzeWithImportedScripts(
184
        psiFile: KtFile,
185
        importedScripts: List<KtFile>,
186
        priority: Int
187
    ): ReplLineAnalysisResultWithStateless
188
}
189

190
/**
191
 * Resolution facade implementation for REPL contexts
192
 */
193
class KotlinResolutionFacadeForRepl(
194
    environment: KotlinCoreEnvironment,
195
    provider: ComponentProvider
196
) : ResolutionFacade {
197
    override val project: Project
198
    override val moduleDescriptor: ModuleDescriptor
199
}
200
```
201

202
### Completion Implementation Functions
203

204
Core completion functionality:
205

206
```kotlin { .api }
207
/**
208
 * Main completion function for JVM REPL
209
 */
210
fun getKJvmCompletion(
211
    ktScript: KtFile,
212
    bindingContext: BindingContext,
213
    resolutionFacade: KotlinResolutionFacadeForRepl,
214
    moduleDescriptor: ModuleDescriptor,
215
    cursor: Int,
216
    configuration: ScriptCompilationConfiguration
217
): Sequence<SourceCodeCompletionVariant>
218

219
/**
220
 * Prepares code for completion analysis by inserting marker string
221
 */
222
fun prepareCodeForCompletion(code: String, cursor: Int): String
223
```
224

225
## Error Handling
226

227
All completion and analysis operations return `ResultWithDiagnostics` which provides:
228

229
- **Success case**: Contains the requested result (completions or analysis)
230
- **Failure case**: Contains diagnostic information about compilation errors
231
- **Diagnostics**: Both success and failure cases may include diagnostic reports
232

233
Common error scenarios:
234
- **Syntax errors**: Invalid Kotlin syntax in the script
235
- **Type errors**: Type mismatches and unresolved references  
236
- **Configuration errors**: Invalid script compilation configuration
237
- **Environment errors**: Issues with the compilation environment or dependencies