| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 3 | 14 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 0 | 1 | 7 | 0% |
What each file covers
Sections
0 shared · 3 only in A · 14 only in B- − CLAUDE.md - Guidelines for Kotlin Development
- − Project Guidelines
- − Individual Preferences
- + 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
0 shared · 1 only in A · 7 only in B- − agent-behaviour
- + test
- + code-style
- + architecture
- + testing-strategy
- + api
- + do-not
- + docs
Line diff
JetBrains/kotlin · CLAUDE.md
@@ −1 @@
1---
2project: Kotlin
3languages: [Kotlin, Java]
4build-system: Gradle
5repository: monorepo
6---
7
8# CLAUDE.md - Guidelines for Kotlin Development
9
10## Project Guidelines
11
12**CRITICAL: @./.ai/guidelines.md guidelines MUST be followed at all times.**
13
14## Individual Preferences
15
16**Local Preferences:** @./.claude/local.md
17
18When asked to update memory, you must update `./.claude/CLAUDE.md` if it is not specified that another file should be modified.
19
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−---
2−project: Kotlin
3−languages: [Kotlin, Java]
4−build-system: Gradle
5−repository: monorepo
6−---
1+# Kotlin PSI (Program Structure Interface)
72
8−# CLAUDE.md - Guidelines for Kotlin Development
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.
94
10−## Project Guidelines
5+## Relationship with Analysis API
116
12−**CRITICAL: @./.ai/guidelines.md guidelines MUST be followed at all times.**
7+PSI provides **syntax** information (structure of code). Analysis API builds on top of PSI to provide **semantic** information (meaning of code).
138
14−## Individual Preferences
9+```
10+Source Code → PSI Tree (syntax) → Analysis API (semantics) → Symbols
11+```
1512
16−**Local Preferences:** @./.claude/local.md
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
1716
18−When asked to update memory, you must update `./.claude/CLAUDE.md` if it is not specified that another file should be modified.
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+```
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+```
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+
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)
19167
