| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 8 | 11 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 1 | 2 | 3 | 17% |
What each file covers
Sections
0 shared · 8 only in A · 11 only in B- − Compiler Architecture
- − Intro
- − Two Frontends
- − FIR Compilation Phases
- − IR (Intermediate Representation)
- − Inference
- − Commit Guidelines
- − Testing
- + FIR Analysis Tests
- + Test File Format (`.kt` files)
- + Header Directives
- + Inline Diagnostic Markers
- + Debug Info Markers
- + Footer
- + Associated Files (auto-generated, not hand-edited)
- + Latest Language Version Differences
- + Creating a New Test
- + Important notes
- + Directory Structure at `testData/resolve/`
Commands
0 shared · 0 only in A · 2 only in B- + ./gradlew :compiler:fir:analysis-tests:test --tests "org.jetbrains.kotlin.test.runners.PhasedJvmDiagnosticLightTreeTestGenerated\$Resolve\$Problems.testMyTest"
- + ./gradlew generateTests
Section tags
1 shared · 2 only in A · 3 only in B- − build
- − git-pr
- + lint-format
- + architecture
- + deployment
- 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/fir/analysis-tests/AGENTS.md
@@ +1 @@
1# FIR Analysis Tests
2
3Location: `compiler/testData/diagnostics`
4
5## Test File Format (`.kt` files)
6
7### Header Directives
8
9Comment lines at the top of the file control test behavior:
10
11| Directive | Description |
12|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
13| `// RUN_PIPELINE_TILL: FRONTEND`, `BACKEND` or `FIR2IR` | How far the compiler pipeline runs (FRONTEND = FIR resolution only, BACKEND = through codegen, FIR2IR = rarely once IR has been created, but failing at backend) |
14| `// ISSUE: KT-XXXXX` | References a YouTrack issue |
15| `// WITH_STDLIB` | Include stdlib in test classpath |
16| `// LANGUAGE: +FeatureName` / `// LANGUAGE: -FeatureName` | Enable/disable language features |
17| `// DIAGNOSTICS: -DIAGNOSTIC_NAME` | Suppress specific diagnostics |
18| `// RENDER_DIAGNOSTICS_FULL_TEXT` | Produces `.fir.diag.txt` with human-readable error messages |
19| `// RENDER_DIAGNOSTIC_ARGUMENTS` | Renders arguments inside markers, e.g. `<!TYPE_MISMATCH("A; B")!>` |
20| `// DUMP_CFG` / `// DUMP_CFG: FLOW` | Generates `.dot` file with control flow graph |
21| `// DUMP_INFERENCE_LOGS: option1, option2` | Possible options: FIXATION, MARKDOWN, MERMAID |
22| `// CHECK_TYPE` | Enables `checkType { _<Type>() }` pattern for type assertions |
23| `// FILE: Name.kt` / `// FILE: Name.java` | Multi-file test (splits single `.kt` file into virtual files) |
24| `// LATEST_LV_DIFFERENCE` | Indicates test expectations differ between stable and latest language version (see `.latestLV.kt` below) |
25
26### Inline Diagnostic Markers
27
28Diagnostic assertions are placed inline around the code that should produce them:
29
30- `<!DIAGNOSTIC_NAME!>code<!>` — asserts `code` produces that diagnostic
31- `<!DIAGNOSTIC_NAME("arg1; arg2")!>code<!>` — with diagnostic arguments (needs `RENDER_DIAGNOSTIC_ARGUMENTS`)
32- `<!DIAG1, DIAG2!>code<!>` — multiple diagnostics on same code span
33
34### Debug Info Markers
35
36- `<!DEBUG_INFO_CALL("fqName: ...; typeCall: ...")!>call<!>` — asserts call resolution target
37- `<!DEBUG_INFO_EXPRESSION_TYPE("type")!>expr<!>` — asserts expression type
38
39### Footer
40
41- `/* GENERATED_FIR_TAGS: tag1, tag2, ... */` — auto-generated tags listing FIR constructs present in the file; do not hand-edit
42
43## Associated Files (auto-generated, not hand-edited)
44
45| Extension | Content | Generated when |
46|------------------|---------------------------------------------------------------------|---------------------------------------------------|
47| `.fir.txt` | FIR tree dump (resolved FIR with `R\|...\|` references) | Only when `FIR_DUMP` directive is present |
48| `.fir.diag.txt` | Diagnostics in text format (`/file.kt:(offset): severity: message`) | `RENDER_DIAGNOSTICS_FULL_TEXT` directive present |
49| `.dot` | Control flow graph in Graphviz format | `DUMP_CFG` directive present |
50| `.fixation.txt` | Type variable fixation process | `DUMP_INFERENCE_LOGS: FIXATION` directive present |
51| `.inference.md` | General type inference logs | `DUMP_INFERENCE_LOGS: MARKDOWN` directive present |
52| `.inference.mmd` | General type inference logs via Mermaid format | `DUMP_INFERENCE_LOGS: MERMAID` directive present |
53| `.latestLV.kt` | Test expectations for latest language version when they differ from stable | `LATEST_LV_DIFFERENCE` directive present |
54
55## Latest Language Version Differences
56
57When a language feature has `sinceVersion` set to a future Kotlin version (e.g., `KOTLIN_2_5`), it is disabled at the stable language version but enabled at the latest language version. This causes different compiler behavior depending on which LV the test runs with.
58
59To handle this:
601. Add `// LATEST_LV_DIFFERENCE` directive to the `.kt` test file
612. Create a `.latestLV.kt` file (for diagnostics tests: `.fir.latestLV.kt` if only FIR behavior differs) containing the full test with diagnostic expectations for the latest LV
623. The base `.kt` file keeps expectations for the stable (default) language version
63
64The latest-LV test runners (`FirLightTreeDiagnosticsWithLatestLanguageVersionTestGenerated`, `FirLightTreeOldFrontendDiagnosticsWithLatestLanguageVersionTestGenerated`) use the `.latestLV.kt` file instead of the base `.kt` file.
65
66Run with `-Pkotlin.test.update.test.data=true` to auto-generate/update `.latestLV.kt` content.
67
68## Creating a New Test
69
701. **Create the `.kt` test file** with appropriate directives and test code.
712. **Regenerate test runners**: `./gradlew generateTests` — updates `*Generated.java` files to include the new test method.
723. **Run the test once** (it will fail):
73 ```bash
74 ./gradlew :compiler:fir:analysis-tests:test --tests "org.jetbrains.kotlin.test.runners.PhasedJvmDiagnosticLightTreeTestGenerated\$Resolve\$Problems.testMyTest"
75 ```
76 This first run auto-generates the `GENERATED_FIR_TAGS` footer in the `.kt` file. No special flags are needed — tags are written automatically on first run.
774. **Run the test again** — it should now pass.
78
79### Important notes
80
81- **`RUN_PIPELINE_TILL` must match actual test needs.** If the test has no expected diagnostics/errors, the framework requires `BACKEND`. Using `FRONTEND` when `BACKEND` is possible causes a "Phase FRONTEND could be promoted to BACKEND" failure.
82- **`GENERATED_FIR_TAGS` are written automatically** on the first test run when absent. Do not add them manually. Just run the test, let it fail and write the tags, then run again.
83- **`.fir.txt` is NOT generated by default.** It requires a `// FIR_DUMP` directive. Most tests (especially simple regression tests) do not need it.
84- **stdlib is not available by default.** Functions like `println` will produce `UNRESOLVED_REFERENCE` without the `// WITH_STDLIB` directive.
85- **`-Pkotlin.test.update.test.data=true`** updates handler-generated files (like `.fir.txt`) but does NOT update the `.kt` source file itself (tags, diagnostic markers). The `.kt` file is updated by the test framework's own `TagsGeneratorChecker` on a normal test run.
86
87## Directory Structure at `testData/resolve/`
88
89Root level contains individual `.kt` test files with their `.fir.txt` dumps. Subdirectories group tests by topic:
90
91- `annotations/`, `arguments/`, `arrays/` — basic language constructs
92- `builtins/`, `stdlib/` — standard library interactions
93- `callResolution/` — call resolution scenarios (overloads, invoke, SAM, operators)
94- `cfa/`, `cfg/` — control flow analysis and graphs
95- `checkers/`, `extraCheckers/`, `diagnostics/` — diagnostic-focused tests
96- `collectionLiterals/`, `constructors/`, `constVal/` — specific constructs
97- `contextParameters/`, `contextSensitiveResolutionUsingExpectedType/` — context-dependent resolution
98- `contracts/` — Kotlin contracts
99- `delegates/`, `destructuring/` — delegation and destructuring
100- `exhaustiveness/` — exhaustive when/sealed checks
101- `expresssions/` (note: misspelled in repo), `fromBuilder/` — expression-level tests
102- `headerMode/` — header/expect declarations
103- `inference/` — type inference
104- `inlineClasses/`, `innerClasses/`, `localClasses/` — class variants
105- `j+k/` — Java-Kotlin interop
106- `multifile/` — multi-file tests (using `// FILE:` directive)
107- `multiplatform/` — multiplatform expect/actual
108- `nestedTypeAliases/`, `typeArguments/`, `typeParameters/`, `types/` — type system
109- `overloadResolution/`, `overrides/` — overloading and overriding
110- `problems/` — regression/bug scenarios
111- `properties/`, `propertyVsField/` — property resolution
112- `qualifiers/`, `references/` — qualified access and references
113- `returnInExpressionBodies/` — return in expression body functions
114- `samConstructors/`, `samConversions/` — SAM conversion tests
115- `scopes/`, `visibility/` — scoping and visibility
116- `scripts/` — Kotlin scripting
117- `smartcasts/` — smart cast tests
118- `suppress/` — @Suppress annotation tests
119- `unqualifiedEnum/` — unqualified enum access
120- `vfir/` — virtual FIR tests
121- `withAllowedKotlinPackage/` — tests allowing kotlin package
122
@@ −1 +1 @@
1−# Compiler Architecture
1+# FIR Analysis Tests
22
3−## Intro
3+Location: `compiler/testData/diagnostics`
44
5−Consider reading [fir-basics.md](../docs/fir/fir-basics.md).
5+## Test File Format (`.kt` files)
66
7−## Two Frontends
7+### Header Directives
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+Comment lines at the top of the file control test behavior:
1110
12−## FIR Compilation Phases
11+| Directive | Description |
12+|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
13+| `// RUN_PIPELINE_TILL: FRONTEND`, `BACKEND` or `FIR2IR` | How far the compiler pipeline runs (FRONTEND = FIR resolution only, BACKEND = through codegen, FIR2IR = rarely once IR has been created, but failing at backend) |
14+| `// ISSUE: KT-XXXXX` | References a YouTrack issue |
15+| `// WITH_STDLIB` | Include stdlib in test classpath |
16+| `// LANGUAGE: +FeatureName` / `// LANGUAGE: -FeatureName` | Enable/disable language features |
17+| `// DIAGNOSTICS: -DIAGNOSTIC_NAME` | Suppress specific diagnostics |
18+| `// RENDER_DIAGNOSTICS_FULL_TEXT` | Produces `.fir.diag.txt` with human-readable error messages |
19+| `// RENDER_DIAGNOSTIC_ARGUMENTS` | Renders arguments inside markers, e.g. `<!TYPE_MISMATCH("A; B")!>` |
20+| `// DUMP_CFG` / `// DUMP_CFG: FLOW` | Generates `.dot` file with control flow graph |
21+| `// DUMP_INFERENCE_LOGS: option1, option2` | Possible options: FIXATION, MARKDOWN, MERMAID |
22+| `// CHECK_TYPE` | Enables `checkType { _<Type>() }` pattern for type assertions |
23+| `// FILE: Name.kt` / `// FILE: Name.java` | Multi-file test (splits single `.kt` file into virtual files) |
24+| `// LATEST_LV_DIFFERENCE` | Indicates test expectations differ between stable and latest language version (see `.latestLV.kt` below) |
1325
14−FIR processes code through sequential phases (see `FirResolvePhase.kt`).
26+### Inline Diagnostic Markers
1527
16−Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.
28+Diagnostic assertions are placed inline around the code that should produce them:
1729
18−## IR (Intermediate Representation)
30+- `<!DIAGNOSTIC_NAME!>code<!>` — asserts `code` produces that diagnostic
31+- `<!DIAGNOSTIC_NAME("arg1; arg2")!>code<!>` — with diagnostic arguments (needs `RENDER_DIAGNOSTIC_ARGUMENTS`)
32+- `<!DIAG1, DIAG2!>code<!>` — multiple diagnostics on same code span
1933
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
34+### Debug Info Markers
2435
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
36+- `<!DEBUG_INFO_CALL("fqName: ...; typeCall: ...")!>call<!>` — asserts call resolution target
37+- `<!DEBUG_INFO_EXPRESSION_TYPE("type")!>expr<!>` — asserts expression type
3038
31−## Inference
39+### Footer
3240
33−For type inference implementation details, read [inference.md](../docs/fir/inference.md).
41+- `/* GENERATED_FIR_TAGS: tag1, tag2, ... */` — auto-generated tags listing FIR constructs present in the file; do not hand-edit
3442
35−## Commit Guidelines
43+## Associated Files (auto-generated, not hand-edited)
3644
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).
45+| Extension | Content | Generated when |
46+|------------------|---------------------------------------------------------------------|---------------------------------------------------|
47+| `.fir.txt` | FIR tree dump (resolved FIR with `R\|...\|` references) | Only when `FIR_DUMP` directive is present |
48+| `.fir.diag.txt` | Diagnostics in text format (`/file.kt:(offset): severity: message`) | `RENDER_DIAGNOSTICS_FULL_TEXT` directive present |
49+| `.dot` | Control flow graph in Graphviz format | `DUMP_CFG` directive present |
50+| `.fixation.txt` | Type variable fixation process | `DUMP_INFERENCE_LOGS: FIXATION` directive present |
51+| `.inference.md` | General type inference logs | `DUMP_INFERENCE_LOGS: MARKDOWN` directive present |
52+| `.inference.mmd` | General type inference logs via Mermaid format | `DUMP_INFERENCE_LOGS: MERMAID` directive present |
53+| `.latestLV.kt` | Test expectations for latest language version when they differ from stable | `LATEST_LV_DIFFERENCE` directive present |
3954
40−## Testing
55+## Latest Language Version Differences
4156
42−For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).
57+When a language feature has `sinceVersion` set to a future Kotlin version (e.g., `KOTLIN_2_5`), it is disabled at the stable language version but enabled at the latest language version. This causes different compiler behavior depending on which LV the test runs with.
58+
59+To handle this:
60+1. Add `// LATEST_LV_DIFFERENCE` directive to the `.kt` test file
61+2. Create a `.latestLV.kt` file (for diagnostics tests: `.fir.latestLV.kt` if only FIR behavior differs) containing the full test with diagnostic expectations for the latest LV
62+3. The base `.kt` file keeps expectations for the stable (default) language version
63+
64+The latest-LV test runners (`FirLightTreeDiagnosticsWithLatestLanguageVersionTestGenerated`, `FirLightTreeOldFrontendDiagnosticsWithLatestLanguageVersionTestGenerated`) use the `.latestLV.kt` file instead of the base `.kt` file.
65+
66+Run with `-Pkotlin.test.update.test.data=true` to auto-generate/update `.latestLV.kt` content.
67+
68+## Creating a New Test
69+
70+1. **Create the `.kt` test file** with appropriate directives and test code.
71+2. **Regenerate test runners**: `./gradlew generateTests` — updates `*Generated.java` files to include the new test method.
72+3. **Run the test once** (it will fail):
73+ ```bash
74+ ./gradlew :compiler:fir:analysis-tests:test --tests "org.jetbrains.kotlin.test.runners.PhasedJvmDiagnosticLightTreeTestGenerated\$Resolve\$Problems.testMyTest"
75+ ```
76+ This first run auto-generates the `GENERATED_FIR_TAGS` footer in the `.kt` file. No special flags are needed — tags are written automatically on first run.
77+4. **Run the test again** — it should now pass.
78+
79+### Important notes
80+
81+- **`RUN_PIPELINE_TILL` must match actual test needs.** If the test has no expected diagnostics/errors, the framework requires `BACKEND`. Using `FRONTEND` when `BACKEND` is possible causes a "Phase FRONTEND could be promoted to BACKEND" failure.
82+- **`GENERATED_FIR_TAGS` are written automatically** on the first test run when absent. Do not add them manually. Just run the test, let it fail and write the tags, then run again.
83+- **`.fir.txt` is NOT generated by default.** It requires a `// FIR_DUMP` directive. Most tests (especially simple regression tests) do not need it.
84+- **stdlib is not available by default.** Functions like `println` will produce `UNRESOLVED_REFERENCE` without the `// WITH_STDLIB` directive.
85+- **`-Pkotlin.test.update.test.data=true`** updates handler-generated files (like `.fir.txt`) but does NOT update the `.kt` source file itself (tags, diagnostic markers). The `.kt` file is updated by the test framework's own `TagsGeneratorChecker` on a normal test run.
86+
87+## Directory Structure at `testData/resolve/`
88+
89+Root level contains individual `.kt` test files with their `.fir.txt` dumps. Subdirectories group tests by topic:
90+
91+- `annotations/`, `arguments/`, `arrays/` — basic language constructs
92+- `builtins/`, `stdlib/` — standard library interactions
93+- `callResolution/` — call resolution scenarios (overloads, invoke, SAM, operators)
94+- `cfa/`, `cfg/` — control flow analysis and graphs
95+- `checkers/`, `extraCheckers/`, `diagnostics/` — diagnostic-focused tests
96+- `collectionLiterals/`, `constructors/`, `constVal/` — specific constructs
97+- `contextParameters/`, `contextSensitiveResolutionUsingExpectedType/` — context-dependent resolution
98+- `contracts/` — Kotlin contracts
99+- `delegates/`, `destructuring/` — delegation and destructuring
100+- `exhaustiveness/` — exhaustive when/sealed checks
101+- `expresssions/` (note: misspelled in repo), `fromBuilder/` — expression-level tests
102+- `headerMode/` — header/expect declarations
103+- `inference/` — type inference
104+- `inlineClasses/`, `innerClasses/`, `localClasses/` — class variants
105+- `j+k/` — Java-Kotlin interop
106+- `multifile/` — multi-file tests (using `// FILE:` directive)
107+- `multiplatform/` — multiplatform expect/actual
108+- `nestedTypeAliases/`, `typeArguments/`, `typeParameters/`, `types/` — type system
109+- `overloadResolution/`, `overrides/` — overloading and overriding
110+- `problems/` — regression/bug scenarios
111+- `properties/`, `propertyVsField/` — property resolution
112+- `qualifiers/`, `references/` — qualified access and references
113+- `returnInExpressionBodies/` — return in expression body functions
114+- `samConstructors/`, `samConversions/` — SAM conversion tests
115+- `scopes/`, `visibility/` — scoping and visibility
116+- `scripts/` — Kotlin scripting
117+- `smartcasts/` — smart cast tests
118+- `suppress/` — @Suppress annotation tests
119+- `unqualifiedEnum/` — unqualified enum access
120+- `vfir/` — virtual FIR tests
121+- `withAllowedKotlinPackage/` — tests allowing kotlin package
122+
