AGENTS.md

1# Kotlin PSI (Program Structure Interface)
2 
3PSI represents Kotlin source code as a syntax tree. It is the foundation for code analysis, navigation, and refactoring in both the compiler and IDE.
4 
5## Relationship with Analysis API
6 
7PSI provides **syntax** information (structure of code). Analysis API builds on top of PSI to provide **semantic** information (meaning of code).
8 
9```
10Source Code → PSI Tree (syntax) → Analysis API (semantics) → Symbols
11```
12 
13- `KtResolvable` interface marks PSI elements that can be resolved to Analysis API symbols
14- When working with PSI, you often need Analysis API to understand what the code means
15- See [analysis/AGENTS.md](../../analysis/AGENTS.md) for Analysis API guidelines
16 
17## Module Structure
18 
19- `psi-api/` - Core PSI interfaces (`KtElement`, `KtExpression`, `KtDeclaration`)
20- `psi-impl/` - Implementations and stubs for incremental compilation
21- `psi-frontend-utils/` - Compiler integration utilities
22- `psi-utils/` - Helper utilities
23 
24## Main Classes
25 
26```
27KtElement (root interface)
28├── KtExpression (calls, literals, operators, etc.)
29│   ├── KtCallExpression
30│   ├── KtBinaryExpression
31│   ├── KtLambdaExpression
32│   └── ...
33└── KtDeclaration (classes, functions, properties)
34    ├── KtClass, KtObjectDeclaration
35    ├── KtNamedFunction
36    ├── KtProperty
37    └── ...
38```
39 
40- `KtFile` - root of a Kotlin file's PSI tree
41- `KtPsiFactory` - factory for creating PSI elements programmatically
42 
43## Key Patterns
44 
45**Visitor pattern** for AST traversal:
46- `KtVisitor<R, D>` - base visitor with return type R and data D
47- `KtTreeVisitor<D>` - recursive tree traversal
48 
49**Stubs** for performance:
50- Binary PSI representation for faster parsing
51- Used for library files and caching
52 
53## PSI Development Rules
54 
55### Shared Principles with Analysis API
56 
57PSI and Analysis API share common development principles. Before contributing:
58 
59→ READ [`analysis/docs/contribution-guide/api-development.md`](../../analysis/docs/contribution-guide/api-development.md) for API design principles
60→ READ [`analysis/docs/contribution-guide/api-evolution.md`](../../analysis/docs/contribution-guide/api-evolution.md) for stability and deprecation
61 
62### Java-Kotlin Interoperability
63 
64**J2K Conversion Limitations:**
65 
66Converting Java PSI classes to Kotlin is NOT always possible. Before attempting:
67 
681. **`@JvmName` unavailable in interfaces** — in some cases it is impossible to convert Java methods to Kotlin properties in a binary-compatible way since `@JvmName` cannot be used to fix potential clashes.
69 
702. **Platform type handling** — IntelliJ Platform APIs use Java types extensively; Kotlin's null-safety interop requires careful handling.
71   - The classic example is `PsiElement.getParent()` returning `PsiElement!`. After conversion to Kotlin it becomes either `PsiElement?` or `PsiElement` – both of them are breaking changes.
72     A workaround is to delegate the implementation to a Java method and keep the return type implicit.
73 
743. **Binary compatibility** — PSI classes are widely used; the binary and source compatibility must be preserved as much as possible.
75 
76**Guidance:** Always consult with PSI maintainers before converting Java classes to Kotlin.
77 
78### PSI-Specific Notes
79 
80**Naming:** All PSI types use the `Kt` prefix (vs `Ka` for Analysis API).
81 
82**Stability annotations:**
83- `@KtExperimentalApi` — Experimental public API
84- `@KtImplementationDetail` — Internal implementation
85- `@KtNonPublicApi` — JetBrains-internal APIs
86- `@KtPsiInconsistencyHandling` — Code handling inconsistent PSI states
87 
88**Java-Kotlin interop:** See the "Java-Kotlin Interoperability" section in [api-development.md](../../analysis/docs/contribution-guide/api-development.md).
89 
90**PSI-specific naming patterns:**
91- `visit` prefix for visitor methods (e.g., `visitCallExpression`)
92- `create` prefix for factory methods in `KtPsiFactory` (e.g., `createExpression`)
93 
94### Documenting KtElement Classes
95 
96General documentation rules from [api-development.md](../../analysis/docs/contribution-guide/api-development.md) apply to all PSI classes. This section describes additional requirements specific to concrete classes implementing `KtElement`.
97 
98**Required documentation for concrete KtElement classes:**
99 
1001. **Class description** — A simple explanation of which Kotlin language concept or syntax construct the class represents.
101 
1022. **Code example** — A code snippet showing the syntax in context. Use ASCII-art markers (`^___^`) to indicate the specific portion that the class represents.
103 
104Example documentation format:
105```kotlin
106/**
107 * Represents a function call expression.
108 *
109 * ### Example:
110 * 
111 * ```kotlin
112 * fun main() {
113 *     println(0)
114 * // ^_________^
115 * }
116 * ```
117 */
118class KtCallExpression : ...
119```
120 
121**Reference examples:**
122- `KtCallExpression` and `KtAnnotationEntry` demonstrate the code example format with ASCII-art markers.
123 
124**Test coverage requirement:**
125 
126All concrete `KtElement` classes must be covered by tests in `compiler/psi/psi-impl/testData/psi/`:
127- Each test consists of a `.kt` file containing example Kotlin code and a corresponding `.txt` file showing the expected PSI tree structure
128- These tests serve as documentation showing which code constructs map to which PSI elements
129- When adding a new `KtElement` class, add corresponding test cases demonstrating the syntax it represents
130 
131## Working with Test Data
132 
133PSI test data (`compiler/psi/psi-impl/testData/`) is managed by the same test data manager as the Analysis API, since the
134`test-data-manager` convention is applied to `:compiler:psi:psi-impl`. When modifying test data files or running generated tests
135(`*Generated`) that compare output against `.txt` files, use `updateTestData` (to rewrite files) or `checkTestData` (to verify only)
136instead of standard test commands.
137 
138```bash
139# Update all PSI test data
140./gradlew :compiler:psi:psi-impl:updateTestData
141 
142# Update by directory (preferred for iteration)
143./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=compiler/psi/psi-impl/testData/psi/annotation/
144```
145 
146Note that a single `.kt` file under `testData/psi/` feeds several suites across two modules: the PSI tree (`.txt`) from
147`:compiler:psi:psi-impl` (`PsiParsingTest`), plus source stubs (`.stubs.txt`), compiled stubs (`.compiled.stubs.txt`,
148`.knm.compiled.stubs.txt`) and decompiled text (`.decompiledText.txt`, `.knm.decompiledText.txt`) from `:analysis:stubs`. Prefer a
149path-filtered `updateTestData` from the repo root so that every affected module is picked up.
150 
151→ READ [`analysis/AGENTS.md`](../../analysis/AGENTS.md) ("Working with Test Data") for the full set of options and the rationale
152 
153## Detailed Documentation
154 
155WHEN modifying PSI interfaces or adding new element types:
156→ Explore [psi-api/src/org/jetbrains/kotlin/psi/](psi-api/src/org/jetbrains/kotlin/psi/) for existing patterns
157 
158WHEN working with PSI visitors:
159→ READ [psi-api/src/org/jetbrains/kotlin/psi/KtVisitor.java](psi-api/src/org/jetbrains/kotlin/psi/KtVisitor.java)
160→ READ [psi-api/src/org/jetbrains/kotlin/psi/KtTreeVisitor.java](psi-api/src/org/jetbrains/kotlin/psi/KtTreeVisitor.java)
161 
162WHEN creating PSI elements programmatically:
163→ READ [psi-api/src/org/jetbrains/kotlin/psi/KtPsiFactory.kt](psi-api/src/org/jetbrains/kotlin/psi/KtPsiFactory.kt)
164 
165WHEN working with stubs:
166→ READ [`analysis/stubs/README.md`](../../analysis/stubs/README.md)
167