| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 8 | 14 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 1 | 2 | 6 | 11% |
What each file covers
Sections
0 shared · 8 only in A · 14 only in B- − Compiler Architecture
- − Intro
- − Two Frontends
- − FIR Compilation Phases
- − IR (Intermediate Representation)
- − Inference
- − Commit Guidelines
- − Testing
- + Kotlin PSI (Program Structure Interface)
- + Relationship with Analysis API
- + Module Structure
- + Main Classes
- + Key Patterns
- + PSI Development Rules
- + Shared Principles with Analysis API
- + Java-Kotlin Interoperability
- + PSI-Specific Notes
- + Documenting KtElement Classes
- + Working with Test Data
- + Update all PSI test data
- + Update by directory (preferred for iteration)
- + Detailed Documentation
Commands
0 shared · 0 only in A · 2 only in B- + ./gradlew :compiler:psi:psi-impl:updateTestData
- + ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=compiler/psi/psi-impl/testData/psi/annotation/
Section tags
1 shared · 2 only in A · 6 only in B- − build
- − git-pr
- + code-style
- + architecture
- + testing-strategy
- + api
- + do-not
- + docs
- test
Line diff
JetBrains/kotlin · compiler/AGENTS.md
@@ −1 @@
1# Compiler Architecture
2
3## Intro
4
5Consider reading [fir-basics.md](../docs/fir/fir-basics.md).
6
7## Two Frontends
8
91. **K1/FE 1.0 (Legacy)**: Located in `compiler/frontend/` - uses PSI and BindingContext
102. **K2/FIR (Current)**: Located in `compiler/fir/` - Frontend IR, the new compiler frontend
11
12## FIR Compilation Phases
13
14FIR processes code through sequential phases (see `FirResolvePhase.kt`).
15
16Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.
17
18## IR (Intermediate Representation)
19
20Located in `compiler/ir/`. Backend IR is used by all targets for:
21- Lowering (transforming code to target-friendly form)
22- Optimization
23- Serialization to klibs
24
25Backend implementations:
26- `compiler/ir/backend.jvm/` - JVM backend
27- `compiler/ir/backend.js/` - JavaScript backend
28- `compiler/ir/backend.wasm/` - WebAssembly backend
29- `kotlin-native/backend.native/`, `native/` - Native backend
30
31## Inference
32
33For type inference implementation details, read [inference.md](../docs/fir/inference.md).
34
35## Commit Guidelines
36
37- **FIR prefix**: When changes are mostly related to FIR (`compiler/fir/`), use `FIR: ` prefix in the commit subject line.
38- **Test-before-fix**: When fixing an issue and adding a test, commit the test data as a separate commit **before** the fix. This helps reviewers see how the fix actually changes semantics (the test will show diagnostic differences in the fix commit).
39
40## Testing
41
42For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).
JetBrains/kotlin · compiler/psi/AGENTS.md
@@ +1 @@
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
@@ −1 +1 @@
1−# Compiler Architecture
1+# Kotlin PSI (Program Structure Interface)
22
3−## Intro
3+PSI represents Kotlin source code as a syntax tree. It is the foundation for code analysis, navigation, and refactoring in both the compiler and IDE.
44
5−Consider reading [fir-basics.md](../docs/fir/fir-basics.md).
5+## Relationship with Analysis API
66
7−## Two Frontends
7+PSI provides **syntax** information (structure of code). Analysis API builds on top of PSI to provide **semantic** information (meaning of code).
88
9−1. **K1/FE 1.0 (Legacy)**: Located in `compiler/frontend/` - uses PSI and BindingContext
10−2. **K2/FIR (Current)**: Located in `compiler/fir/` - Frontend IR, the new compiler frontend
9+```
10+Source Code → PSI Tree (syntax) → Analysis API (semantics) → Symbols
11+```
1112
12−## FIR Compilation Phases
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
1316
14−FIR processes code through sequential phases (see `FirResolvePhase.kt`).
17+## Module Structure
1518
16−Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.
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
1723
18−## IR (Intermediate Representation)
24+## Main Classes
1925
20−Located in `compiler/ir/`. Backend IR is used by all targets for:
21−- Lowering (transforming code to target-friendly form)
22−- Optimization
23−- Serialization to klibs
26+```
27+KtElement (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+```
2439
25−Backend implementations:
26−- `compiler/ir/backend.jvm/` - JVM backend
27−- `compiler/ir/backend.js/` - JavaScript backend
28−- `compiler/ir/backend.wasm/` - WebAssembly backend
29−- `kotlin-native/backend.native/`, `native/` - Native backend
40+- `KtFile` - root of a Kotlin file's PSI tree
41+- `KtPsiFactory` - factory for creating PSI elements programmatically
3042
31−## Inference
43+## Key Patterns
3244
33−For type inference implementation details, read [inference.md](../docs/fir/inference.md).
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
3448
35−## Commit Guidelines
49+**Stubs** for performance:
50+- Binary PSI representation for faster parsing
51+- Used for library files and caching
3652
37−- **FIR prefix**: When changes are mostly related to FIR (`compiler/fir/`), use `FIR: ` prefix in the commit subject line.
38−- **Test-before-fix**: When fixing an issue and adding a test, commit the test data as a separate commit **before** the fix. This helps reviewers see how the fix actually changes semantics (the test will show diagnostic differences in the fix commit).
53+## PSI Development Rules
3954
40−## Testing
55+### Shared Principles with Analysis API
4156
42−For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).
57+PSI 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+
66+Converting Java PSI classes to Kotlin is NOT always possible. Before attempting:
67+
68+1. **`@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+
70+2. **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+
74+3. **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+
96+General 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+
100+1. **Class description** — A simple explanation of which Kotlin language concept or syntax construct the class represents.
101+
102+2. **Code example** — A code snippet showing the syntax in context. Use ASCII-art markers (`^___^`) to indicate the specific portion that the class represents.
103+
104+Example 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+ */
118+class 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+
126+All 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+
133+PSI 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)
136+instead 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+
146+Note 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
149+path-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+
155+WHEN 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+
158+WHEN 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+
162+WHEN 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+
165+WHEN working with stubs:
166+→ READ [`analysis/stubs/README.md`](../../analysis/stubs/README.md)
167+
