Comparison

A · AGENTS.md · JetBrains/kotlin B · AGENTS.md · JetBrains/kotlin

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	8	14	0%
Commands	0	0	6	0%
Section tags	1	2	4	14%

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
+ Analysis API Guidelines
+ Architecture
+ Relationship with PSI
+ Key Conventions
+ Working with Test Data
+ `updateTestData` — the only recommended way to update test data
+ Update test data by directory (preferred for iteration)
+ Update test data by test class pattern
+ Run only golden tests (useful for quick baseline updates)
+ Incremental update — only re-run variant tests for changed paths
+ Limit to a subset of modules using task paths (Gradle task-name matching)
+ `checkTestData` — verification only
+ Key Components
+ Detailed Documentation

Commands

0 shared · 0 only in A · 6 only in B

+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/
+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*
+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true
+ ./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true
+ ./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData
+ ./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/

Section tags

1 shared · 2 only in A · 4 only in B

− build
− git-pr
+ code-style
+ architecture
+ api
+ docs
test

Line diff

+103 added−26 removed16 unchanged13.5% identical

JetBrains/kotlin · compiler/AGENTS.md

@@ −1 @@

1# Compiler Architecture

3## Intro

5Consider reading [fir-basics.md](../docs/fir/fir-basics.md).

7## Two Frontends

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

12## FIR Compilation Phases

14FIR processes code through sequential phases (see `FirResolvePhase.kt`).

16Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.

18## IR (Intermediate Representation)

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

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

31## Inference

33For type inference implementation details, read [inference.md](../docs/fir/inference.md).

35## Commit Guidelines

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).

40## Testing

42For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).

JetBrains/kotlin · analysis/AGENTS.md

@@ +1 @@

1# Analysis API Guidelines

3A library for analyzing Kotlin code at the semantic level, providing structured access to symbols, types, and semantic relationships.

5**Entry point:** Use [`analyze()`](analysis-api/src/org/jetbrains/kotlin/analysis/api/analyze.kt) to start an analysis session. See [Analysis API documentation](https://kotl.in/analysis-api) for a usage guide.

7## Architecture

9- **Platform** — Provides declarations, project structure, and modification events (IntelliJ, Standalone)

10- **Engine** — Performs code analysis using platform-provided information (K1, K2)

11- **User** — Code that calls `analyze()` to work with symbols and types

13→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md) for detailed architecture overview

15## Relationship with PSI

17Analysis API builds on top of Kotlin PSI (`compiler/psi/`):

18- **PSI** provides syntax (structure of code): `KtElement`, `KtExpression`, `KtDeclaration`

19- **Analysis API** provides semantics (meaning of code): `KaSymbol`, `KaType`

21```

22PSI (syntax) → Analysis API (semantics) → Symbols, Types, Resolution

23```

25**Both PSI and Analysis API follow shared development principles** documented in [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md).

27WHEN working with PSI elements:

28→ READ [`compiler/psi/AGENTS.md`](../compiler/psi/AGENTS.md) for PSI-specific rules and conventions

30## Key Conventions

32- `Ka` prefix for Analysis API types, `Kt` for PSI types

33- Prefer interfaces to classes for better binary compatibility

34- Properties for attributes, functions for actions with parameters

35- Return nullable types for operations that can fail (avoid exceptions for non-exceptional cases)

36- All implementations must validate lifetime ownership with `withValidityAssertion`

37- Mark experimental APIs with `@KaExperimentalApi`, implementation details with `@KaImplementationDetail`

39## Working with Test Data

41When modifying test data files or running generated tests (`*Generated`) that compare output against `.txt` files, use `updateTestData` (to rewrite files) or `checkTestData` (to verify only) instead of standard test commands. Both take their options as `-P` properties, so changing filters between runs stays fast.

43### `updateTestData` — the only recommended way to update test data

45```bash

46# Update test data by directory (preferred for iteration)

47./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/

49# Update test data by test class pattern

50./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*

52# Run only golden tests (useful for quick baseline updates)

53./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true

55# Incremental update — only re-run variant tests for changed paths

56./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true

58# Limit to a subset of modules using task paths (Gradle task-name matching)

59./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData

60```

62`updateTestData` is fixed to update mode. There is no `updateTestDataGlobally` — Gradle's task-name matching runs the task in every applicable subproject when invoked from the repo root.

64### `checkTestData` — verification only

66If you specifically need to verify that existing test data is consistent without modifying anything (e.g., sanity-checking generated files after an `updateTestData` run), use `checkTestData`. It is the exact `-P`-driven counterpart of `updateTestData` but fixed to check mode: it fails on any mismatch and writes nothing.

68```bash

69./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/

70```

72Use this only for verification. For any workflow that writes test data, use `updateTestData`.

74**Why use these tasks instead of plain `:test`?**

75- Run only relevant tests (filtered by path or class pattern)

76- Handle variant chains correctly (golden `.txt` files run before variant-specific `.js.txt`, `.wasm.txt`, etc.)

77- Automatically discover all modules that use managed test data

78- Detect and remove redundant variant files

80For full options, see [test-data-manager-convention](../repo/gradle-build-conventions/test-data-manager-convention/README.md).

82## Key Components

84- [`analysis-api/`](analysis-api) - User-facing API surface (`KaSession`, `KaSymbol`, `KaType`)

85- [`analysis-api-platform-interface/`](analysis-api-platform-interface) - Platform abstraction (declaration providers, project structure, lifetime)

86- [`analysis-api-standalone/`](analysis-api-standalone) - CLI-based implementation of the Analysis API

87- [`analysis-api-fir/`](analysis-api-fir) - K2 implementation based on FIR

88- [`analysis-api-impl-base/`](analysis-api-impl-base) - Shared implementation utilities

89- [`low-level-api-fir/`](low-level-api-fir) - K2-specific infrastructure for lazy/incremental analysis

90- [`symbol-light-classes/`](symbol-light-classes) - Java PSI view of Kotlin declarations for interop

91- [`decompiled/light-classes-for-decompiled`](decompiled/light-classes-for-decompiled) - Light classes for decompiled/library code

92- [`test-data-manager/`](test-data-manager) - Infrastructure for managing test data files with variant chains

94## Detailed Documentation

96WHEN adding or modifying API endpoints:

97→ READ [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md)

99WHEN deprecating API or understanding stability categories:

100→ READ [`docs/contribution-guide/api-evolution.md`](docs/contribution-guide/api-evolution.md)

101

102WHEN implementing platform components:

103→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md)

104

105WHEN working with light classes:

106→ READ [`symbol-light-classes/README.md`](symbol-light-classes/README.md)

107

108WHEN working with lazy resolution (LL API):

109→ READ [`low-level-api-fir/README.md`](low-level-api-fir/README.md)

110

111WHEN writing or managing test data files:

112→ READ [`test-data-manager/AGENTS.md`](test-data-manager/AGENTS.md)

113

114WHEN seeking historical context on design decisions:

115→ READ [`docs/design-documents/README.md`](docs/design-documents/README.md) (these are historical snapshots, not necessarily up to date)

116

117WHEN working with stubs:

118→ READ [`stubs/README.md`](stubs/README.md)

119

@@ −1 +1 @@

1−# Compiler Architecture

1+# Analysis API Guidelines

3−## Intro

3+A library for analyzing Kotlin code at the semantic level, providing structured access to symbols, types, and semantic relationships.

5−Consider reading [fir-basics.md](../docs/fir/fir-basics.md).

5+**Entry point:** Use [`analyze()`](analysis-api/src/org/jetbrains/kotlin/analysis/api/analyze.kt) to start an analysis session. See [Analysis API documentation](https://kotl.in/analysis-api) for a usage guide.

7−## Two Frontends

7+## Architecture

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+- **Platform** — Provides declarations, project structure, and modification events (IntelliJ, Standalone)

10+- **Engine** — Performs code analysis using platform-provided information (K1, K2)

11+- **User** — Code that calls `analyze()` to work with symbols and types

1112

12−## FIR Compilation Phases

13+→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md) for detailed architecture overview

1314

14−FIR processes code through sequential phases (see `FirResolvePhase.kt`).

15+## Relationship with PSI

1516

16−Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.

17+Analysis API builds on top of Kotlin PSI (`compiler/psi/`):

18+- **PSI** provides syntax (structure of code): `KtElement`, `KtExpression`, `KtDeclaration`

19+- **Analysis API** provides semantics (meaning of code): `KaSymbol`, `KaType`

1720

18−## IR (Intermediate Representation)

21+```

22+PSI (syntax) → Analysis API (semantics) → Symbols, Types, Resolution

23+```

1924

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

25+**Both PSI and Analysis API follow shared development principles** documented in [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md).

2426

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

27+WHEN working with PSI elements:

28+→ READ [`compiler/psi/AGENTS.md`](../compiler/psi/AGENTS.md) for PSI-specific rules and conventions

3029

31−## Inference

30+## Key Conventions

3231

33−For type inference implementation details, read [inference.md](../docs/fir/inference.md).

32+- `Ka` prefix for Analysis API types, `Kt` for PSI types

33+- Prefer interfaces to classes for better binary compatibility

34+- Properties for attributes, functions for actions with parameters

35+- Return nullable types for operations that can fail (avoid exceptions for non-exceptional cases)

36+- All implementations must validate lifetime ownership with `withValidityAssertion`

37+- Mark experimental APIs with `@KaExperimentalApi`, implementation details with `@KaImplementationDetail`

3438

35−## Commit Guidelines

39+## Working with Test Data

3640

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).

41+When modifying test data files or running generated tests (`*Generated`) that compare output against `.txt` files, use `updateTestData` (to rewrite files) or `checkTestData` (to verify only) instead of standard test commands. Both take their options as `-P` properties, so changing filters between runs stays fast.

3942

40−## Testing

43+### `updateTestData` — the only recommended way to update test data

4144

42−For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).

45+```bash

46+# Update test data by directory (preferred for iteration)

47+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/

48+

49+# Update test data by test class pattern

50+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.testClassPattern=.*ResolveTest.*

51+

52+# Run only golden tests (useful for quick baseline updates)

53+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.goldenOnly=true

54+

55+# Incremental update — only re-run variant tests for changed paths

56+./gradlew updateTestData -Porg.jetbrains.kotlin.testDataManager.options.incremental=true

57+

58+# Limit to a subset of modules using task paths (Gradle task-name matching)

59+./gradlew :analysis:analysis-api-fir:updateTestData :analysis:stubs:updateTestData

60+```

61+

62+`updateTestData` is fixed to update mode. There is no `updateTestDataGlobally` — Gradle's task-name matching runs the task in every applicable subproject when invoked from the repo root.

63+

64+### `checkTestData` — verification only

65+

66+If you specifically need to verify that existing test data is consistent without modifying anything (e.g., sanity-checking generated files after an `updateTestData` run), use `checkTestData`. It is the exact `-P`-driven counterpart of `updateTestData` but fixed to check mode: it fails on any mismatch and writes nothing.

67+

68+```bash

69+./gradlew checkTestData -Porg.jetbrains.kotlin.testDataManager.options.testDataPath=analysis/analysis-api/testData/components/resolver/singleByPsi/

70+```

71+

72+Use this only for verification. For any workflow that writes test data, use `updateTestData`.

73+

74+**Why use these tasks instead of plain `:test`?**

75+- Run only relevant tests (filtered by path or class pattern)

76+- Handle variant chains correctly (golden `.txt` files run before variant-specific `.js.txt`, `.wasm.txt`, etc.)

77+- Automatically discover all modules that use managed test data

78+- Detect and remove redundant variant files

79+

80+For full options, see [test-data-manager-convention](../repo/gradle-build-conventions/test-data-manager-convention/README.md).

81+

82+## Key Components

83+

84+- [`analysis-api/`](analysis-api) - User-facing API surface (`KaSession`, `KaSymbol`, `KaType`)

85+- [`analysis-api-platform-interface/`](analysis-api-platform-interface) - Platform abstraction (declaration providers, project structure, lifetime)

86+- [`analysis-api-standalone/`](analysis-api-standalone) - CLI-based implementation of the Analysis API

87+- [`analysis-api-fir/`](analysis-api-fir) - K2 implementation based on FIR

88+- [`analysis-api-impl-base/`](analysis-api-impl-base) - Shared implementation utilities

89+- [`low-level-api-fir/`](low-level-api-fir) - K2-specific infrastructure for lazy/incremental analysis

90+- [`symbol-light-classes/`](symbol-light-classes) - Java PSI view of Kotlin declarations for interop

91+- [`decompiled/light-classes-for-decompiled`](decompiled/light-classes-for-decompiled) - Light classes for decompiled/library code

92+- [`test-data-manager/`](test-data-manager) - Infrastructure for managing test data files with variant chains

93+

94+## Detailed Documentation

95+

96+WHEN adding or modifying API endpoints:

97+→ READ [`docs/contribution-guide/api-development.md`](docs/contribution-guide/api-development.md)

98+

99+WHEN deprecating API or understanding stability categories:

100+→ READ [`docs/contribution-guide/api-evolution.md`](docs/contribution-guide/api-evolution.md)

101+

102+WHEN implementing platform components:

103+→ READ [`analysis-api-platform-interface/README.md`](analysis-api-platform-interface/README.md)

104+

105+WHEN working with light classes:

106+→ READ [`symbol-light-classes/README.md`](symbol-light-classes/README.md)

107+

108+WHEN working with lazy resolution (LL API):

109+→ READ [`low-level-api-fir/README.md`](low-level-api-fir/README.md)

110+

111+WHEN writing or managing test data files:

112+→ READ [`test-data-manager/AGENTS.md`](test-data-manager/AGENTS.md)

113+

114+WHEN seeking historical context on design decisions:

115+→ READ [`docs/design-documents/README.md`](docs/design-documents/README.md) (these are historical snapshots, not necessarily up to date)

116+

117+WHEN working with stubs:

118+→ READ [`stubs/README.md`](stubs/README.md)

119+